Secure Payments Interface API

note

The Secure Payments Interface (SPI) was previously named the Payment Isolation Gateway Interface (PIGI).

Your storefront can send actions to the Secure Payments Interface (SPI) 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 the SPI works, refer to the Concepts page. For information on integrating the SPI into your headless checkout, refer to the Integrate SPI page.

Terminology

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

Actions are commands sent from the parent to the SPI. Each action has a corresponding response. If an action fails, an error message is displayed to the end user.
Responses are messages sent from the SPI 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 SPI <iframe> element.
A message is a JavaScript variable sent to SPI 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 SPI:

{
  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 the SPI (measured in pixels) when the response message sends.

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

The SPI 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 SPI 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 the SPI if a customer updates their order after the SPI 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 SPI:

{
  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 the SPI (measured in pixels) when the response message sends.

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

Example message sent from the SPI 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 the SPI. This action requires a payload that contains the new language in ISO-639-1 format.

Example message sent from the parent to the SPI:

{
  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 the SPI (measured in pixels) when the response message sends.

The SPI 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 the SPI endpoint enables you to change the CSS styling for the SPI user interface. This endpoint defines media rules, which make changes to the CSS under certain conditions.

Every time the SPI initializes (and the parent receives the SPI 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 the SPI. 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#SPI");
  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 SPI](/api/checkout#operation/CreateCSSStylingForSPI) 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 the SPI:

{
  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 the SPI (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 the SPI.
- string sub_type - type of error, corresponds to payment gateway name.

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

Example message sent from the parent to the SPI:

{
  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 the SPI (measured in pixels) when the response message sends.

The SPI sends this response to the parent when the error successfully displays.

Example message sent from the SPI 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 the SPI when you want to remove the error message from the user interface.

Example message sent from the parent to the SPI:

{
  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 the SPI (measured in pixels) when the response message sends.

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

Example message sent from the SPI 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 the SPI to reflect the customer's choice of payment method. Either the index or gatewayName is required. If both are used, the SPI uses index.

Example message sent from the parent to the SPI:

{
  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 the SPI (measured in pixels) when the response message sends.

The SPI sends this response when the payment method has been selected.

Example message sent from the SPI 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 the SPI when you receive a 202 error in response to calling the Process Order endpoint.

Example message sent from the parent to the SPI:

{
  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 the SPI (measured in pixels) when the response message sends.

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

Example message sent from the SPI 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 the SPI iframe. This code should resize the the SPI 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 the SPI 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 the SPI.

Initialize Response

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

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

Example message sent from the SPI to the parent:

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

Update Height Response

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

The SPI sends this message when the document height is updated.

Example message sent from the SPI to the parent:

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

Display In Full Page Response

string responseType: PIGI_DISPLAY_IN_FULL_PAGE
object payload:
- boolean success

The SPI sends this message when the payment gateway requires the iframe to be displayed as full-screen.

Example message sent from the SPI to the parent:

{
  responseType: 'PIGI_DISPLAY_IN_FULL_PAGE',
  payload: {
    success: true,
  },
}

Display In Full Page Done Response

string responseType: PIGI_DISPLAY_IN_FULL_PAGE_DONE
object payload:
- boolean success

The SPI sends this message when it no longer requires the iframe to be full-screen (when the iframe was previously made full-screen by the PIGI_DISPLAY_IN_FULL_PAGE event response). This response indicates that the previous display state can be restored.

Example message sent from the SPI to the parent:

{
  responseType: 'PIGI_DISPLAY_IN_FULL_PAGE_DONE',
  payload: {
    success: true,
  },
}

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​

Initialize Response​

Update Height Response​

Display In Full Page Response​

Display In Full Page Done 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

Initialize Response

Update Height Response

Display In Full Page Response

Display In Full Page Done Response