Specifications

Introduction

Magento Integration Bus (referred as MIB from now on in this document) is an API gateway providing a common communication layer for different applications in the Magento ecosystem See Magento Integration Bus for more details on this topic. The purpose of this document is to provide more details on the payment messages specification

OMS Payments messages

The MIB payments specification describes the fields and format used by the various payments related messages supported by the system.

Although all payment messages are implemented as MIB Commands, they can be divided into two types: commands and notifications:

  • Commands originate from OMS are actions to be taken on a payment.
  • Notifications originate from the payment gateway, and indicated the outcome of the payment command.

An important thing to remember is that all commands are asynchronous. In other words, even if a payment gateway provides a real-time response to a given payment command, a separate notification with the outcome of the command is expected to be sent. This was done because different payment gateways implement standard operations in very different ways.

Payment Commands

As stated before, commands instruct the receiver to perform some actions. The following commands are supported by the MIB:

  • magento.payments.payments_management.validate
    Upon receiving a new order containing a payment, OMS asks for validation of the payment details before proceeding with further actions. The receiver of the message should confirm that the payment instrument exists and is in a valid state. Depending on the payment instrument the verification involve different steps, such as: ensuring there are enough funds in the related account, checking that the payment authorization has not expired, etc.
  • magento.payments.payments_management.revalidate
    For long lived orders - such as pre-orders and back-orders - OMS asks for revalidation of the payment transaction before shipping the goods. The receiver of the message should either confirm that the payment transaction is still valid or generate a new one.
  • magento.payments.payments_management.capture
    When the merchant is ready to ship the ordered goods to the customer, OMS asks for the authorized money to be transferred from the customer’s account to a merchant’s account. Normally capture is requested after the shipment of the ordered goods, but for PayPal payments, capture is requested before shipment.
  • magento.payments.payments_management.refund
    When merchant receives returned goods, or a customer appeasement is required, OMS asks for compensation to be paid to the customer
  • magento.payments.payments_management.cancel
    When an order has been canceled, OMS asks for the payment transaction to be canceled to have the authorization hold released from the customer money.

Please note that adapting a payment command to the API exposed by a payment provider may end up in multiple messages being sent to the payment provider. Coordination of these messages and the generation of the appropriate response is responsibility of the command receiver.

Payment Notifications

Notifications are used to notify about the outcome of a payment command. The following are described by the payments specification.

  • In response to validate command:

    • magento.payments.payments_management.notify_validated
      Indicates that the associated payment transaction has been confirmed to be known by the payment provider and in a valid state.
    • magento.payments.payments_management.notify_validation_failed
      Indicates that the associated payment transaction is either unknown by the payment provider or in a invalid state (i.e. the authorization has expired).
  • In response to a revalidate command:

    • magento.payments.payments_management.notify_revalidated
      Indicates either that the payment transaction passed in is still valid, or that the details of a valid new one to be used in place of the original one are passed back.

    • magento.payments.payments_management.notify_revalidation_failed
      Indicates that the payment transaction passed in is not valid, and it was impossible to generate a valid new one that could be used in the place of the original one.

  • In response to a capture command:

    • magento.payments.payments_management.notify_captured
      Indicates that the transfer of funds between the customer’s and merchant’s account has completed successfully. Be aware that this is different from the payment provider accepting the request and the final confirmation (either success or failure) for the transfer of funds may take some days to be received.

    • magento.payments.payments_management.notify_capture_failed
      Indicates that the transfer of funds between the customer’s and merchant’s account has failed.

  • In response to a refund command:

    • magento.payments.payments_management.notify_refunded
      Indicates that the transfer of funds between the customer’s and merchant’s account has completed successfully. Be aware that this is different from the payment provider accepting the request and the final confirmation (either success or failure) for the transfer of funds may take some days to be received.
    • magento.payments.payments_management.notify_refund_failed
      Indicates that the transfer of funds between the customer’s and merchant’s account has failed.
  • In response to a cancel command:

    • magento.payments.payments_management.notify_cancelled
      Indicates that the payment transaction was successfully cancelled.

    • magento.payments.payments_management.notify_cancellation_failed
      Indicates that it was impossible to cancel the payment transaction.

The technical details (format and fields) for the payment message specifications can be found in the Specifications Section - Payments Management Documentation.

Note that for the sake of simplicity, the same “Payment” model is used for all payment messages, even though a fair number of fields might not be used in most cases.

Enpoints

Endpoints, at a very high level, represent a “place” where messages are exchanged across applications in MIB. An application lets MIB know that it is interested in a particular type of messages by making a call to the MIB registration API. See the Magento Integration Bus “Endpoints” and “Registration” sections for more details on these topics.

Details of the Payment Endpoints (custom payment and reno-proxy) can be found below.

Custom payment endpoint

A custom payment integration needs to register itself to a “custom-payment” endpoint to receive any payment command targeted to the payment provider it handles.

The “custom-payment” endpoint details are:

  • id: custom-payment
  • URL: http://url-where-payment-commands-will-be-handled
  • contracts: magento.payments.payments_management

A registration message similar to this:

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "magento.service_bus.remote.register",
  "params": {
    "id": "custom-payment",
    "url": "http://url-where-payment-commands-will-be-handled",
    "contracts" : [
      "magento.payments.payments_management"
    ]
  }
}

It should be sent to the MIB base endpoint URL: https://integrationbus.mcom.magento.com/<client_id>/

From a system integrator perspective, it means that any payment command targeted to the payment provider handled by the integration, will be dropped by RENO in the MIB custom payment endpoint delegate URL and forwarded by the MIB to the http://url-where-payment-commands-will-be-handled URL where it is expected to be handled by the integration code.

The format of the MIB custom payment endpoint delegate URL is - as stated in the Magento Integration Bus “Endpoints” documentation - as follows:https://integrationbus.mcom.magento.com/<client_id>/delegate/custom-payment

Reno-proxy endpoint

RENO registers itself to a “reno-proxy” endpoint to receive any payment event sent to this endpoint.

The “reno-proxy” endpoint details are:

  • id: reno-proxy
  • contracts: magento.payments.payments_management
  • subscribes:
    • magento.payments.payments_management.notify_validated
    • magento.payments.payments_management.notify_validation_failed
    • magento.payments.payments_management.notify_revalidated
    • magento.payments.payments_management.notify_revalidation_failed
    • magento.payments.payments_management.notify_captured
    • magento.payments.payments_management.notify_capture_failed
    • magento.payments.payments_management.notify_refunded
    • magento.payments.payments_management.notify_refund_failed
    • magento.payments.payments_management.notify_cancelled
    • magento.payments.payments_management.notify_cancellation_failed

From a system integrator perspective, it means that any payment event dropped by the custom payment integration code to the MIB reno-proxy endpoint delegate URL will be forwarded to RENO by the so the MIB.

The format of the MIB reno-proxy endpoint delegate URL is - as stated in the Magento Integration Bus “Endpoints” documentation - as follows: https://integrationbus.mcom.magento.com/<client_id>/delegate/reno-proxy

Authorization

MIB requires any incoming request to be OAuth 2.0 authorized. See the Magento Integration Bus Guide “Authorization” section for more details on this topic.

See the OMS Custom Payment Integration Guide and RENO DIY Integration Guide documents for more details on this topic.