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.

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": "LANGUAGE_CHANGE",
"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
actionTypestringBILLING_ADDRESS_CHANGED
Example
{
"actionType": "BILLING_ADDRESS_CHANGED"
}

Billing Address Changed response

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

Language Change

Language Change action

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

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

Language Change response

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

Media

Media action

Send this action to update the iframe document size.

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

Media response

Attributes
NameTypeDescription
responseTypestringMEDIA
payload[success]booleanSet to true when the MEDIA action succeeds.
Example
{
"responseType": "MEDIA",
"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
actionTypestringSHIPPING_ADDRESS_CHANGED
Example
{
"actionType": "SHIPPING_ADDRESS_CHANGED"
}

Shipping Address Changed response

Attributes
NameTypeDescription
responseTypestringSHIPPING_ADDRESS_CHANGED
payload[success]booleanSet to true when the SHIPPING_ADDRESS_CHANGED action succeeds.
Example
{
"responseType": "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
actionTypestringUPDATE_STATE
Example
{
"actionType": "UPDATE_STATE"
}

Update State response

Attributes
NameTypeDescription
responseTypestringUPDATE_STATE
payload[success]booleanSet to true when the UPDATE_STATE action succeeds.
Example
{
"responseType": "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
responseTypestringADD_PAYMENT
payload[success]booleanSet to true when the 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": "ADD_PAYMENT",
"payload": {
"success": true,
"paymentType": "CREDIT_CARD",
"height": 120
}
}

Refresh

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

Attributes

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

Example

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

Tokenizing Complete

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

Attributes

NameTypeDescription
responseTypestringTOKENIZING_COMPLETE
payload[success]booleanSet to true when the TOKENIZING_COMPLETE event succeeds.

Example

{
"responseType": "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
responseTypestringTOKENIZING_IN_PROGRESS
payload[success]booleanSet to true when the TOKENIZING_IN_PROGRESS event succeeds.

Example

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