Skip to main content

External Payment Gateway Actions and Events

Bold Checkout can send actions to the external payment gateway through the iframe and receive responses back. Both actions and responses are sent via the Window.postMessage() method.

For more information on integrating external payment gateways with Checkout, see the Integrate an External Payment Gateway guide.

For more information implementing an external payment gateway connector, see the External Payment Gateway Connector API page.

Terminology​

Throughout this reference page, note the following terms:

  • The parent is the DOM containing the external payment gateway iframe element.
  • Actions are commands sent from the parent to the iframe.
  • Events are commands sent from the iframe to the parent.

The parent must be the target_div used to register the external payment gateway. See the target_div field in the Register the External Payment Gateway example request.

Actions​

Actions are structured as simple JSON objects, which your external payment gateway connector must include in the response to a Checkout event.

Each action has the following keys:

KeyTypeDescription
actionTypestringIdentifies the action to perform.
payloadobject(Optional) Contains parameters specific to the action type.

This code snippet demonstrates a response body containing one action:

{
  "success": true,
  "actions": [
    {
      "type": "EXTERNAL_PAYMENT_GATEWAY_UPDATE_LANGUAGE",
      "payload": {
        "language": "en"
      }
    }
  ]
}

The "actions" array can contain any number of actions, including 0.

Similarly, each response has the following keys:

KeyTypeDescription
responseTypestringIdentifies the action performed.
payloadobjectContains parameters specific to the response type.

Checkout uses the following Window.postMessage() actions to interact with the iframe.

Billing Address Changed​

Billing Address Changed action​

Send when any of the of the Billing Address API endpoints successfully resolve.

Attributes​
NameTypeDescription
actionTypestringEXTERNAL_PAYMENT_GATEWAY_BILLING_ADDRESS_CHANGED
Example​
{
  "actionType": "EXTERNAL_PAYMENT_GATEWAY_BILLING_ADDRESS_CHANGED"
}

Billing Address Changed response​

Attributes​
NameTypeDescription
responseTypestringEXTERNAL_PAYMENT_GATEWAY_BILLING_ADDRESS_CHANGED
payload[success]booleanSet to true when the EXTERNAL_PAYMENT_GATEWAY_BILLING_ADDRESS_CHANGED action succeeds.
Example​
{
  "responseType": "EXTERNAL_PAYMENT_GATEWAY_BILLING_ADDRESS_CHANGED",
  "payload": {
    "success": true
  }
}

Update Language​

Update Language action​

Send this action to change the language displayed in the iframe.

Attributes​
NameTypeDescription
actionTypestringEXTERNAL_PAYMENT_GATEWAY_UPDATE_LANGUAGE
languagestringThe new language in ISO-639-1 format.
Example​
{
  "actionType": "EXTERNAL_PAYMENT_GATEWAY_UPDATE_LANGUAGE",
  "payload": {
    "language": "en"
  }
}

Update Language response​

Attributes​
NameTypeDescription
responseTypestringEXTERNAL_PAYMENT_GATEWAY_UPDATE_LANGUAGE
payload[success]booleanSet to true when the EXTERNAL_PAYMENT_GATEWAY_UPDATE_LANGUAGE action succeeds.
payload[height]numberThe height of the DOM containing the iframe when the response message is sent, measured in pixels.
Example​
{
  "responseType": "EXTERNAL_PAYMENT_GATEWAY_UPDATE_LANGUAGE",
  "payload": {
    "success": true,
    "height": 120
  }
}

Update Height​

Update height action​

Send this action to update the iframe document size.

Attributes​
NameTypeDescription
actionTypestringEXTERNAL_PAYMENT_GATEWAY_UPDATE_HEIGHT
payload[height]numberThe updated height of the DOM that contains the iframe, measured in pixels.
Example​
{
  "actionType": "EXTERNAL_PAYMENT_GATEWAY_UPDATE_HEIGHT",
  "payload": {
    "height": 120
  }
}

Media response​

Attributes​
NameTypeDescription
responseTypestringEXTERNAL_PAYMENT_GATEWAY_UPDATE_HEIGHT
payload[success]booleanSet to true when the EXTERNAL_PAYMENT_GATEWAY_UPDATE_HEIGHT action succeeds.
Example​
{
  "responseType": "EXTERNAL_PAYMENT_GATEWAY_UPDATE_HEIGHT",
  "payload": {
    "success": true
  }
}

Shipping Address Changed​

Shipping Address Changed action​

Send this action when any of the Shipping Address API endpoints successfully resolve.

Attributes​
NameTypeDescription
actionTypestringEXTERNAL_PAYMENT_GATEWAY_SHIPPING_ADDRESS_CHANGED
Example​
{
  "actionType": "EXTERNAL_PAYMENT_GATEWAY_SHIPPING_ADDRESS_CHANGED"
}

Shipping Address Changed response​

Attributes​
NameTypeDescription
responseTypestringEXTERNAL_PAYMENT_GATEWAY_SHIPPING_ADDRESS_CHANGED
payload[success]booleanSet to true when the EXTERNAL_PAYMENT_GATEWAY_SHIPPING_ADDRESS_CHANGED action succeeds.
Example​
{
  "responseType": "EXTERNAL_PAYMENT_GATEWAY_SHIPPING_ADDRESS_CHANGED",
  "payload": {
    "success": true
  }
}

Update State​

Update State action​

Send this action when the application state changes. Forwards the application state to the iframe.

Attributes​
NameTypeDescription
actionTypestringEXTERNAL_PAYMENT_GATEWAY_UPDATE_STATE
Example​
{
  "actionType": "EXTERNAL_PAYMENT_GATEWAY_UPDATE_STATE"
}

Update State response​

Attributes​
NameTypeDescription
responseTypestringEXTERNAL_PAYMENT_GATEWAY_UPDATE_STATE
payload[success]booleanSet to true when the EXTERNAL_PAYMENT_GATEWAY_UPDATE_STATE action succeeds.
Example​
{
  "responseType": "EXTERNAL_PAYMENT_GATEWAY_UPDATE_STATE",
  "payload": {
    "success": true
  }
}

Events​

Some messages sent by the iframe to the parent are not in response to an action sent from the parent but letting the parent know an event has happened within the iframe.

Add Payment​

The iframe sends this event to the parent when:

  • the payment has been successfully added to the order, or
  • a customer adds a gift card payment to the order.

You may wish to update the order information in the parent window to display the new outstanding balance.

Attributes​

NameTypeDescription
responseTypestringEXTERNAL_PAYMENT_GATEWAY_ADD_PAYMENT
payload[success]booleanSet to true when the EXTERNAL_PAYMENT_GATEWAY_ADD_PAYMENT action succeeds.
payload[paymentType]stringThe type of payment method added. Possible values are CREDIT_CARD, BRANDED_CARD, GIFT_CARD, or PAYPAL.
payload[height]numberThe height of the DOM containing the iframe when the event is sent, measured in pixels.

Example​

{
  "responseType": "EXTERNAL_PAYMENT_GATEWAY_ADD_PAYMENT",
  "payload": {
    "success": true,
    "paymentType": "CREDIT_CARD",
    "height": 120
  }
}

Refresh Order​

The iframe sends this event to the parent when it successfully refreshes the order and receives the current application state.

Attributes​

NameTypeDescription
responseTypestringEXTERNAL_PAYMENT_GATEWAY_REFRESH_ORDER
payload[success]booleanSet to true when the EXTERNAL_PAYMENT_GATEWAY_REFRESH_ORDER event succeeds.
payload[height]numberThe height of the DOM containing the iframe when the event is sent, measured in pixels.

Example​

{
  "responseType": "EXTERNAL_PAYMENT_GATEWAY_REFRESH_ORDER",
  "payload": {
    "success": true,
    "height": 120
  }
}

Tokenizing Complete​

Indicates tokenization is complete. Checkout can resume processing the order.

Attributes​

NameTypeDescription
responseTypestringEXTERNAL_PAYMENT_GATEWAY_TOKENIZING_COMPLETE
payload[success]booleanSet to true when the EXTERNAL_PAYMENT_GATEWAY_TOKENIZING_COMPLETE event succeeds.

Example​

{
  "responseType": "EXTERNAL_PAYMENT_GATEWAY_TOKENIZING_COMPLETE",
  "payload": {
    "success": true
  }
}

Tokenizing In Progress​

Indicates tokenization is in progress. Checkout will block all incoming API calls until sent the TOKENIZING_COMPLETE event.

Attributes​

NameTypeDescription
responseTypestringEXTERNAL_PAYMENT_GATEWAY_TOKENIZING_IN_PROGRESS
payload[success]booleanSet to true when the EXTERNAL_PAYMENT_GATEWAY_TOKENIZING_IN_PROGRESS event succeeds.

Example​

{
  "responseType": "EXTERNAL_PAYMENT_GATEWAY_TOKENIZING_IN_PROGRESS",
  "payload": {
    "success": true
  }
}