Skip to main content

External Payment Gateways

External payment gateways allow developers to integrate any payment gateway with Bold Checkout.

External payment gateways

An external payment gateway is any payment gateway not already supported by Bold. Stores can replace their default Bold Checkout payment gateway with an external payment gateway or add an external payment gateway in addition to their default gateway.

To communicate with Bold, the external payment gateway must send and receive data with specific endpoints. Bold calls these endpoints the external payment gateway connector. To implement a connector, use the Integrate an External Payment Gateway guide.

External payment gateway information flow

When implementing an external payment gateway, a store provides Bold with information required to display the external payment gateway's iframe. This information includes:

  • an iframe_url, the store's external payment gateway URL to place in a frontend iframe, e.g.

  • a target_div element, informing Bold where to display the iframe in the Checkout frontend.

When an order is initialized using the Initialize Order endpoint, the iframe information is displayed in the storefront's checkout page. Once a customer enters payment information in the iframe, the following occurs:

  1. Checkout sends the payment information to the external payment gateway iframe.
  2. The external payment gateway returns a token associating the customer with the transaction.
  3. The storefront sends the token and payment information to the Checkout Frontend API Create Payment endpoint.
  4. Checkout sends this information to the external payment gateway's Retain endpoint.
  5. The storefront and the external payment gateway complete the order, using Checkout Backend API and External Payment Gateway API endpoints.

Frontend information flow

In the information flow above, the first step is:

  1. Checkout sends the payment information to the external payment gateway iframe.

The following is a more detailed explanation of how the iframe is created:

  1. The Checkout Frontend API sends application state data to the Checkout frontend display.
  2. Checkout completes the following tasks:
    1. Checks the application state data for information about external payment providers, such as iframe_urls and target_divs.
    2. Grabs the iframe_url and requests the target_div element from the application state.
    3. Scans the DOM for the requested target_div. If the element exists, the iframe is loaded from the iframe_url.
    4. Interacts with the iframe via the postMessage() API.

For more information on the postMessage() API actions and events, see the External Payment Gateway Actions and Events page.