Payment

The Magento Order Management System (OMS) can handle payments via Pre-built integrations, like Braintree, Ingenico, or PayPal via Custom payment integrations or the Offline method.

Captures (settlements) and refunds, as well as any payment notifications, will be performed by the OMS. The payments must be authorized on the front-end at the time of checkout, by the sales channel (such as the webstore), and implemented by partners.

Payment references are then passed to the OMS in the order message. These references do not include sensitive information, such as credit card numbers. They are tokens that will help the OMS complete the next payment interaction (refund, capture, or re-authorization).

The OMS also has to be configured with the same credentials as the front-end in order to be able to communicate with a payment provider, such as Braintree or PayPal.

Pre-built integrations

OMS proposes an out-of-the-box integration with Braintree and PayPal.

Braintree

The out-of-the-box Braintree integration supports the following features:

  • Capture of the amount
    • After the last shipment it will capture the amount of the shipped items, including the shipping costs, which may be less than the authorized amount in case of cancelled items.
    • After X days, or after the last shipment (the first event occurring)—
      • After X days the objective is to capture before the authorization expires (some cards, like Carte Bleue in France, expire after 6 days) even though the order is not yet shipped. A refund will be triggered if any lines are subsequently cancelled.
      • After the last shipment it will capture the amount of the shipped items (including the shipping costs), which may be less than the authorized amount in case of cancelled items.
    • Before the first shipment request is sent; A refund will be triggered if any lines are subsequently cancelled.
  • Refunds due to cancellations, appeasements, or returns
  • Manual retries for failed refunds in the OMS backoffice; These can arise, for example, when the PayPal account has been auto-swept and there were no funds in the merchant PayPal account with which to make a refund. Subsequent payments would make the refund possible again.
  • Notifications of capture (and refunds) confirmations (usually from 3-15 days on average), which can be monitored, in case they are not received in a timely fashion.

This pre-built integration doesn’t currently support multi-capture (i.e. at every shipment).

Ingenico

The OMS does not currently support Ingenico payments. For more information about Ingenico payments see the Ingenico website.

If your OMS uses Ingenico for payments contact your Technical Account Manager (TAM) for assistance in finishing the migration to a new payment provider.

PayPal

The Paypal integration is used for payments initiated in the webstore with PayPal, and up to the authorization stage (SetExpress, GetExpress, DoExpress, and DoAuth). The out-of-the-box integration supports the following features:

  • Capture of the amount
    • Before the first shipment request is sent (a refund will be triggered if any lines are subsequently cancelled). This is recommended by PayPal because some captures (around 2-3%) fail after authorization.
    • After the last shipment it will capture the amount of the shipped items, including the shipping costs, which may be less than the authorized amount in case of cancelled items.
    • After X days, or after the last shipment (the first event occurring)—
      • After X days the objective is to capture before the authorization expires (some cards, like Carte Bleue in France, expire after 6 days) even though the order is not yet shipped. A refund will be triggered if any lines are subsequently cancelled.
      • After the last shipment it will capture the amount of the shipped items, including the shipping costs, which may be less than the authorized amount in case of cancelled items.
  • Refunds due to cancellations, appeasements, or returns
  • Manual retries for failed refunds in the OMS backoffice
  • Notifications of capture confirmations (usually within 15 minutes), which can be monitored in case they are not received in a timely fashion.

This pre-built integration doesn’t currently support multi-capture (i.e. at every shipment).

Custom payment integrations

Custom Payment Integration allows to integrate with any payment service provider by adapting standard OMS messages to the format expected by the payment service provider. More details about the integration are available here: Custom Payment Integration.

As for the pre-built integration, no sensitive payment information (like credit card number) must be sent to the OMS. The OMS will only use tokens.

This custom integration supports the following features:

  • Capture of the amount—
    • After the last shipment it will capture the amount of the shipped items (including the shipping costs), which may be less than the authorized amount (for cancelled items).
    • After X days, or after the last shipment, (the first event occurring):
        • After X days the objective is to capture before the authorization expires (some cards like Carte Bleue In France expire after 6 days) even though the order is not yet shipped. A refund will be triggered if any lines are subsequently canceled.
      • After the last shipment it will capture the amount of the shipped items, including the shipping costs, which may be less than the authorized amount (for canceled items).
    • Before the first shipment request is sent (a refund will be triggered if any lines are subsequently cancelled).
    • After each shipment (multi-captures) it captures the amount of the shipped items once a day. For partially shipped orders it captures the remaining amount right after the last shipment.
  • Refunds due to cancellations, appeasements or returns
  • Manual retries for failed refunds in the OMS backoffice
  • Notifications of capture confirmations (may be multiple days depending on the payment method), which can be monitored if they are not received in a timely fashion.

Offline method

Payment methods can be processed offline, meaning that your OMS is not responsible of the payment process. The payment is managed outside of the OMS.

For more information, see the Offline payments page.

Payment event status

This table shows all the payment events statuses that are available in your OMS:

Payment Event Status Payment Events Description
RECEIVED All payment events Means that OMS was able to deliver the payment request to its destination successfully. Destinations are Radial payment API or Reno.
SUCCESS All payment events Means that OMS received a positive response for the initial payment request.
FAULT All payment events Means that OMS was not able to deliver the payment request to its destination. Usually due to a technical error. This status is picked by the systemic retry process.
FAILURE All payment events Means that OMS was not able to perform the payment operation, for example a Capture. When retry attempts are expired this status is also used.
PENDING All payment events Means that the payment event will retried later through the Retry On Hold job. This is a recovery backdoor.
AUTHORIZED Authorizations only Payment was authorised successfully.

These different statuses can occur throughout the order life of your OMS, depending on the payment integration used.

In this instance, the webstore does both the authorization and the capture before passing it to the OMS. Orders are then considered to have had their payments already processed “Offline”, meaning that the OMS is not responsible for any captures or refunds. OMS creates dummy records to ensure that the reporting structure is unaffected.

If the payment is managed by Magento Commerce, the Connector should be customized to process payments based on events occurring in this order:

  • The webstore may do the authorization and the capture before passing it all to the OMS. In this case, refunds may have to be triggered in Magento Commerce in case of cancellations, appeasements, or returns.
  • It is possible to just do the authorization in the webstore. In this case, the OMS messages should be caught by the Connector and should trigger actions, such as creating an invoice and capturing it online in Magento Commerce. In this case, this action will send the capture to the payment gateway, unless the payment method was set up to authorize and capture at the time of purchase via the payment action setting (in which case submitting an invoice will not result in a capture since it will already be considered complete.)

Testing

No matter the method, we recommend extensive testing in staging and production prior to opening to the public. Sufficient time should be allocated for this important activity. With payments, production is always different than staging, even in subtle ways, due to the way real credit cards and banks process transactions.

Canceled orders

When an order is canceled, the OMS is processing that cancellation, and the order is in the final LOGISTICSCOMPLETE stage for order cleanup, decisions need to be made about how the payment is handled.

Regardless of whether payments are captured up-front before anything is shipped, or after a shipment, payment providers still perform authorization on those payment methods immediately after an order happens at checkout.

If a payment has yet to be captured, the OMS will ensure that the authorization is voided. If a capture was already performed, the OMS automatically contacts the payment provider with a request to trigger the refund, releasing the amount previously allocated for the payment.