Payment Isolation Gateway Interface API

Your storefront can send actions to the Payment Isolation Gateway Interface (PIGI) and receive responses back. Both actions and responses consist of messages sent via the Window.postMessage() method. This reference includes all the possible actions and associated responses.

note

For information on how PIGI works, refer to the Concepts page. For information on integrating PIGI into your headless checkout, refer to the Integrate PIGI page.

Terminology

Throughout the following reference, keep the following terms in mind:

Actions are commands sent from the parent to PIGI. Each action has a corresponding response. If an action fails, an error message is displayed to the end user.
Responses are messages sent from PIGI back to the parent. Most responses are sent after an action is complete, but some are independent from the actions.
The parent is the DOM containing the PIGI <iframe> element.
A message is a JavaScript variable sent to PIGI or the parent using Window.postMessage().

Add Payment

Add Payment Action

string actionType: PIGI_ADD_PAYMENT

Send this action to tokenize the customer-entered payment information and add that token to the order. This action does not authorize or capture the payment.

Example message sent from parent to PIGI:

{
  actionType: 'PIGI_ADD_PAYMENT',
}

Add Payment Response

string responseType: PIGI_ADD_PAYMENT
object payload:
- string paymentType - Acceptable values are CREDIT_CARD, BRANDED_CARD, GIFT_CARD, or PAYPAL.
- boolean success - true when the PIGI_ADD_PAYMENT action succeeds.
- number height - the height of the DOM that contains PIGI (measured in pixels) when the response message sends.

PIGI sends this response to the parent when the payment has been successfully added to the order.

PIGI also sends this response to the parent when a customer adds a gift card payment to the order, because the gift card payment method contains its own button and requires no instructions to add the payment. You may wish to update the order information in the parent window to display the new outstanding balance.

Example message sent from PIGI to parent:

{
  responseType: 'PIGI_ADD_PAYMENT',
  payload: {
    paymentType: 'CREDIT_CARD',
    success: true,
    height: 120,
  },
}

Refresh Order

Refresh Order Action

string actionType: PIGI_REFRESH_ORDER

Send this action to PIGI if a customer updates their order after PIGI was first displayed (e.g., if a customer updates the order line items). Payment gateways require updated information about the customer or order to add the payment to the order.

Example message sent from the parent to PIGI:

{
  actionType: 'PIGI_REFRESH_ORDER',
}

Refresh Order Response

string responseType: PIGI_REFRESH_ORDER
object payload:
- boolean success - true when the PIGI_REFRESH_ORDER action succeeds.
- number height - the height of the DOM that contains PIGI (measured in pixels) when the response message sends.

PIGI sends this message back to the parent when it successfully refreshes the order.

Example message sent from PIGI to the parent:

{
  responseType: 'PIGI_REFRESH_ORDER',
  payload: {
    success: true,
    height: 120,
  },
}

Update Language

Update Language Action

string actionType: PIGI_UPDATE_LANGUAGE
object payload:
- string language - language ISO in ISO-639-1 format.

Send this action to change the language displayed in PIGI. This action requires a payload that contains the new language in ISO-639-1 format.

Example message sent from the parent to PIGI:

{
  actionType: 'PIGI_UPDATE_LANGUAGE',
  payload: {
    language: 'en',
  },
}

Update Language Response

string responseType: PIGI_UPDATE_LANGUAGE
object payload:
- boolean success - true when the PIGI_UPDATE_LANGUAGE action succeeds.
- number height - the height of the DOM that contains PIGI (measured in pixels) when the response message sends.

PIGI sends this response back to the parent when it successfully updates the language.

Example message sent back to the parent:

{
  responseType: 'PIGI_UPDATE_LANGUAGE',
  payload: {
    success: true,
    height: 120,
  },
}

Update Media Match

Update Media Match Action

string actionType: PIGI_UPDATE_MEDIA_MATCH
object payload:
- string conditionText - media rule condition.
- boolean matches - whether or not the condition was met.

The Create CSS Styling for PIGI endpoint enables you to change the CSS styling for PIGI user interface. This endpoint defines media rules, which make changes to the CSS under certain conditions.

Every time PIGI initializes (and the parent receives the PIGI Initialize Response), check whether the media rules have changed. If the the media rules have changed, use the PIGI_UPDATE_MEDIA_MATCH action to pass the new media rule to PIGI. You can do so by adding a listener — the following JavaScript snippet shows an example:

function updateMediaMatch(event) {
  const payload = {
    conditionText: event.media,
    matches: event.matches,
  };
  const iframeElement = document.querySelector("iframe#PIGI");
  const iframeWindow = iframeElement.contentWindow;
  const action = { actionType: "PIGI_UPDATE_MEDIA_MATCH", payload };
  iframeWindow.postMessage(action, "*");
}

// The following media rules are a result of a call to the [Create CSS Styling for PIGI](/api/checkout#operation/CreateCSSStylingForPIGI) endpoint.

const mediaRules = [
  {
    conditionText: "screen and (max-height: 600px)",
    cssRules: [
      {
        cssText: ".ToggleField__Text { color:blue; }",
      },
    ],
  },
];
mediaRules.forEach((rule) => {
  const mediaMatch = window.matchMedia(rule.conditionText);
  mediaMatch.addListener(updateMediaMatch);
  updateMediaMatch(mediaMatch);
});

The following example shows the PIGI_UPDATE_MEDIA_MATCH sent from the parent to PIGI:

{
  actionType: 'PIGI_UPDATE_MEDIA_MATCH',
  payload: {
    conditionText: 'screen and (min-width: 768px)',
    matches: false
  },
}

Update Media Match Response

string responseType: PIGI_UPDATE_MEDIA_MATCH
object payload:
- boolean success - true when the PIGI_UPDATE_MEDIA_MATCH action succeeds.
- number height - the height of the DOM that contains PIGI (measured in pixels) when the response message sends.

Example message sent back to the parent:

{
  responseType: 'PIGI_UPDATE_MEDIA_MATCH',
  payload: {
    success: true,
    height: 120,
  },
}

Display Error Message

Display Error Message Action

string actionType: PIGI_DISPLAY_ERROR_MESSAGE
object payload:
- string message - error message to display in PIGI.
- string sub_type - type of error, corresponds to payment gateway name.

Send this action to PIGI to display an error message in the user interface. The sub_type of error helps PIGI determine where to display the error. You can display more than one error at a time.

Example message sent from the parent to PIGI:

{
  actionType: 'PIGI_DISPLAY_ERROR_MESSAGE',
  payload: {
    error: {
      message: 'message to be displayed',
      sub_type: 'string_to_categorize_error',
    },
  },
}

Display Error Message Response

string responseType: PIGI_DISPLAY_ERROR_MESSAGE
object payload:
- boolean success - true when the PIGI_DISPLAY_ERROR_MESSAGE action succeeds.
- number height - the height of the DOM that contains PIGI (measured in pixels) when the response message sends.

PIGI sends this response to the parent when the error successfully displays.

Example message sent from PIGI to the parent:

{
  responseType: 'PIGI_DISPLAY_ERROR_MESSAGE',
  payload: {
    success: true,
    height: 120,
  },
}

Clear Error Messages

Clear Error Messages Action

string actionType: PIGI_CLEAR_ERROR_MESSAGES

Send this message to PIGI when you want to remove the error message from the user interface.

Example message sent from the parent to PIGI:

{
  actionType: 'PIGI_CLEAR_ERROR_MESSAGES',
}

Clear Error Messages Response

string responseType: PIGI_CLEAR_ERROR_MESSAGES
object payload:
- boolean success - true when the PIGI_CLEAR_ERROR_MESSAGES action succeeds
- number height - the height of the DOM that contains PIGI (measured in pixels) when the response message sends.

PIGI sends this message to the parent when it successfully removes any error messages.

Example message sent from PIGI to the parent:

{
  responseType: 'PIGI_CLEAR_ERROR_MESSAGES',
  payload: {
    success: true,
    height: 120,
  },
}

Select Payment Method

Select Payment Method Action

string responseType: PIGI_SELECT_PAYMENT_METHOD
object payload:
- number index - the index of the payment gateway method to be selected.
- string gatewayName - the gateway name of the payment gateway method to be selected. The available names include: stripe, authorize, spreedly, qualpay, braintree, paysafe, moneris, adyen, cybersource, paypal_paypal, paypal_braintree, flexiti, branded_flexiti, branded_paysafe, and amazon

Send this action to PIGI to reflect the customer's choice of payment method. Either the index or gatewayName is required. If both are used, PIGI uses index.

Example message sent from the parent to PIGI:

{
  actionType: 'PIGI_SELECT_PAYMENT_METHOD',
  payload: {
    gatewayName: 'stripe',
  },
}

Select Payment Method Response

string responseType: PIGI_SELECT_PAYMENT_METHOD
object payload:
- boolean success - true when the PIGI_SELECT_PAYMENT_METHOD action succeeds.
- number height - the height of the DOM that contains PIGI (measured in pixels) when the response message sends.

PIGI sends this response when the payment method has been selected.

Example message sent from PIGI to the parent:

{
  responseType: 'PIGI_SELECT_PAYMENT_METHOD',
  payload: {
    success: true,
    height: 120,
  },
}

Handle SCA

Handle SCA Action

string responseType: PIGI_HANDLE_SCA
object payload:

Send this action to PIGI when you receive a 202 error in response to calling the Process Order endpoint.

Example message sent from the parent to PIGI:

{
  actionType: "PIGI_HANDLE_SCA";
}

Handle SCA Response

string responseType: PIGI_HANDLE_SCA
object payload:
- string step - the status of the 3DS authentication. Possible values are DISPLAYED, COMPLETED, or FAILED.
- boolean success - true when the PIGI_HANDLE_SCA action succeeds.
- number height - the height of the DOM that contains PIGI (measured in pixels) when the response message sends.

PIGI uses 3D Secure (3DS) to prompt the customer to verify their identity. PIGI then sends several responses that indicate when the 3DS interface is displayed and when the authentication is complete.

Example message sent from PIGI to the parent:

{
  responseType: 'PIGI_HANDLE_SCA',
  payload: {
    step: 'DISPLAYED'
    success: true,
    height: 120,
  },
}

The parent must handle this response and act appropriately. The following JavaScript snippet provides an example of handling the PIGI_HANDLE_SCA response:

window.addEventListener('message', ({ data }) => {
  const type = data.responseType;
  switch (type) {
    case 'PIGI_HANDLE_SCA':
      switch (data.payload.step) {
      case 'DISPLAYED':
        // Code for when the 3DS screen is displayed within the PIGI iframe. This code should resize the PIGI iframe accordingly.
        break;
      case 'COMPLETED':
        // Code for when authentication is successful. The frontend should make another call to the Process Order endpoint.
        break;
      case 'FAILED':
        // Code for when authentication is not successful.
        break;
      default:
    }
      break;
  }
}

Event-driven responses

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

PIGI Initialize Response

string responseType: PIGI_INITIALIZED
object payload:
- boolean success
- number height - the height of the DOM that contains PIGI (measured in pixels) when the response message sends.

PIGI sends this message when it successfully loads and is ready to start receiving actions.

Example message sent from PIGI to the parent:

{
  responseType: 'PIGI_INITIALIZED',
  payload: {
    success: true,
    height: 120,
  },
}

PIGI Update Height Response

string responseType: PIGI_UPDATE_HEIGHT
object payload:
- boolean success
- number height - the height of the DOM that contains PIGI (measured in pixels) when the response message sends.

PIGI sends this message when the document height is updated.

Example message sent from PIGI to the parent:

{
  responseType: 'PIGI_UPDATE_HEIGHT',
  payload: {
    success: true,
    height: 120,
  },
}

Terminology​

Add Payment​

Add Payment Action​

Add Payment Response​

Refresh Order​

Refresh Order Action​

Refresh Order Response​

Update Language​

Update Language Action​

Update Language Response​

Update Media Match​

Update Media Match Action​

Update Media Match Response​

Display Error Message​

Display Error Message Action​

Display Error Message Response​

Clear Error Messages​

Clear Error Messages Action​

Clear Error Messages Response​

Select Payment Method​

Select Payment Method Action​

Select Payment Method Response​

Handle SCA​

Handle SCA Action​

Handle SCA Response​

Event-driven responses​

PIGI Initialize Response​

PIGI Update Height Response​

Terminology

Add Payment

Add Payment Action

Add Payment Response

Refresh Order

Refresh Order Action

Refresh Order Response

Update Language

Update Language Action

Update Language Response

Update Media Match

Update Media Match Action

Update Media Match Response

Display Error Message

Display Error Message Action

Display Error Message Response

Clear Error Messages

Clear Error Messages Action

Clear Error Messages Response

Select Payment Method

Select Payment Method Action

Select Payment Method Response

Handle SCA

Handle SCA Action

Handle SCA Response

Event-driven responses

PIGI Initialize Response

PIGI Update Height Response