In an eCommerce ecosystem, payment interactions primarily take place in two areas: in the checkout & in the order management system (OMS). In the following sections, we’ll explore the architecture behind these functional areas and the foundational concepts that must be maintained for any payment gateway integration. From there, we’ll review how you can build a new payment gateway integration.
Renders payment options fetched from the checkout payment method option endpoint
Gathers payment method data from customer input and/or the customer’s profile
Interacts with the payment gateway to tokenize the payment method data
Coordinates the amount that will be paid with each selected payment option
|For frontend SDK library support across payment gateways, see our payment SDK.|
Provides the list of available payment method options in checkout
Coordinates cart & checkout-related processes
Validates the cart’s payments & that they cover the cart total
Coordinates the execution of checkout-related payment transactions (esp. authorizations or authorizationAndCaptures), calling PaymentTransactionServices to execute the transactions
Coordinates post-checkout order management processes like fulfilling, cancelling fulfillments, & returning items
Coordinates the execution of payment transactions (esp. captures & refunds) for fulfillment-related processes, calling PaymentTransactionServices to execute the transactions
Stores the Payment representation (i.e. how much will be paid against which payment method)
Stores the customer’s saved payments representation for re-use of the payment
Executes payment transactions against payment gateway integrations
Keeps a record of payment transaction interactions and results
Integrates the payment transaction execution plumbing of PaymentTransactionServices with calls to the payment gateway’s APIs
Maps PaymentRequest payloads from PaymentTransactionServices into gateway API requests, calls the gateway’s API, & interprets the response into a PaymentResponse, which PaymentTransactionServices uses to record transaction results.
|To get a better sense of how checkout is processed via the services/resources listed above, checkout the Checkout Payment Architecture document.|
The frontend can be responsible for executing payment transactions, but we strongly prefer executing payment transactions via PaymentTransactionServices. The primary reason for this is our ability to know when payment transactions have been attempted/executed.
Before sending a transaction to the payment gateway, the PaymentTransactionService first records a PaymentTransaction with status