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:

Key	Type	Description
actionType	string	Identifies the action to perform.
payload	object	(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:

Key	Type	Description
responseType	string	Identifies the action performed.
payload	object	Contains 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

Name	Type	Description
actionType	string	EXTERNAL_PAYMENT_GATEWAY_BILLING_ADDRESS_CHANGED

Example

{
  "actionType": "EXTERNAL_PAYMENT_GATEWAY_BILLING_ADDRESS_CHANGED"
}

Billing Address Changed response

Attributes

Name	Type	Description
responseType	string	EXTERNAL_PAYMENT_GATEWAY_BILLING_ADDRESS_CHANGED
payload[success]	boolean	Set 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

Name	Type	Description
actionType	string	EXTERNAL_PAYMENT_GATEWAY_UPDATE_LANGUAGE
language	string	The new language in ISO-639-1 format.

Example

{
  "actionType": "EXTERNAL_PAYMENT_GATEWAY_UPDATE_LANGUAGE",
  "payload": {
    "language": "en"
  }
}

Update Language response

Attributes

Name	Type	Description
responseType	string	EXTERNAL_PAYMENT_GATEWAY_UPDATE_LANGUAGE
payload[success]	boolean	Set to true when the EXTERNAL_PAYMENT_GATEWAY_UPDATE_LANGUAGE action succeeds.
payload[height]	number	The 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

Name	Type	Description
actionType	string	EXTERNAL_PAYMENT_GATEWAY_UPDATE_HEIGHT
payload[height]	number	The 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

Name	Type	Description
responseType	string	EXTERNAL_PAYMENT_GATEWAY_UPDATE_HEIGHT
payload[success]	boolean	Set 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

Name	Type	Description
actionType	string	EXTERNAL_PAYMENT_GATEWAY_SHIPPING_ADDRESS_CHANGED

Example

{
  "actionType": "EXTERNAL_PAYMENT_GATEWAY_SHIPPING_ADDRESS_CHANGED"
}

Shipping Address Changed response

Attributes

Name	Type	Description
responseType	string	EXTERNAL_PAYMENT_GATEWAY_SHIPPING_ADDRESS_CHANGED
payload[success]	boolean	Set 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

Name	Type	Description
actionType	string	EXTERNAL_PAYMENT_GATEWAY_UPDATE_STATE

Example

{
  "actionType": "EXTERNAL_PAYMENT_GATEWAY_UPDATE_STATE"
}

Update State response

Attributes

Name	Type	Description
responseType	string	EXTERNAL_PAYMENT_GATEWAY_UPDATE_STATE
payload[success]	boolean	Set 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

Name	Type	Description
responseType	string	EXTERNAL_PAYMENT_GATEWAY_ADD_PAYMENT
payload[success]	boolean	Set to true when the EXTERNAL_PAYMENT_GATEWAY_ADD_PAYMENT action succeeds.
payload[paymentType]	string	The type of payment method added. Possible values are CREDIT_CARD, BRANDED_CARD, GIFT_CARD, or PAYPAL.
payload[height]	number	The 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

Name	Type	Description
responseType	string	EXTERNAL_PAYMENT_GATEWAY_REFRESH_ORDER
payload[success]	boolean	Set to true when the EXTERNAL_PAYMENT_GATEWAY_REFRESH_ORDER event succeeds.
payload[height]	number	The 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

Name	Type	Description
responseType	string	EXTERNAL_PAYMENT_GATEWAY_TOKENIZING_COMPLETE
payload[success]	boolean	Set 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

Name	Type	Description
responseType	string	EXTERNAL_PAYMENT_GATEWAY_TOKENIZING_IN_PROGRESS
payload[success]	boolean	Set to true when the EXTERNAL_PAYMENT_GATEWAY_TOKENIZING_IN_PROGRESS event succeeds.

Example

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