Specifications

The Magento Integration Bus (MIB) is an API gateway which provides a common communication layer for different services in the Order Management System (OMS) and Magento Commerce (MC) ecosystem. See Magento Integration Bus for more information.

Payment specifications

MIB payment specifications describe the fields and format used in the different payment configurations supported by the OMS.

Although all payment messages are implemented as MIB commands, they can be of two types:

  • Commands originated from the OMS and are actions to be taken on a payment.
  • Notifications originated from the payment gateway and indicate the outcome of that payment command.

All commands are asynchronous, which means that even if a payment gateway provides a real-time response to a specific payment command, a notification with the outcome of the command is always expected to be sent. This allows for different implementation strategies in your payment configuration.

Payment Commands

The MIB supports the following payment commands:

  • 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 involves different steps, such as ensuring there are enough funds in the related account, checking that the payment authorization has not expired, and more.
  • magento.payments.payments_management.revalidate—For long lived orders, such as pre-orders and back-orders, the 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, the 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 a merchant receives returned goods, or a customer appeasement is required, the OMS asks for compensation to be paid to the customer.
  • magento.payments.payments_management.cancel—When an order has been canceled, the OMS asks for the payment transaction to be canceled to release the authorization hold from the customer’s money.

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

Payment notifications are the expected responses to the following commands:

Validate command:

  • magento.payments.payments_management.notify_validated—Indicates that the associated payment transaction is known by the payment provider and is 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 is in an invalid state (i.e. the authorization has expired).

Revalidate command:

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

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

Capture command:

  • magento.payments.payments_management.notify_captured—Indicates that the transfer of funds between the customer and merchant accounts has completed successfully. This is different from the payment provider accepting the request and the final confirmation (either success or failure) because the transfer of funds may take several 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 failed.

Refund command:

  • magento.payments.payments_management.notify_refunded—Indicates that the transfer of funds between the customer and merchant accounts completed successfully. This is different from the payment provider accepting the request. The final confirmation (either success or failure) for the transfer of funds may take several days to be received.

  • magento.payments.payments_management.notify_refund_failed—Indicates that the transfer of funds between the customer and merchant accounts failed.

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 same payment model has been used for all payment messages, even though several fields are not used in most of these cases.

See the #magento.payments.payments_management spec for more information.

Enpoints

Endpoints are a location where messages are exchanged across applications in the MIB. An application lets the MIB know that it is interested in a particular type of messages by making a call to the MIB registration API. See Magento Integration Bus for more information.

Custom payment endpoint

A custom payment integration must 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

Example of a registration message

{
  "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"
    ]
  }
}

This is sent to the MIB base endpoint URL, https://integrationbus.mcom.magento.com/<client_id>/.

From an SI’s perspective, this means that any payment command targeted to the payment provider, handled by the integration, is dropped 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:

https://integrationbus.mcom.magento.com/<client_id>/delegate/custom-payment

See Magento Integration Bus for more information about endpoints.

Authorization

MIB requires any incoming request to be OAuth 2.0 authorized. See the Magento Integration Bus guide for more information.

© 2023 Adobe. All rights reserved.