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
  }
}