Skip to main content
Unlisted page
This page is unlisted. Search engines will not index it, and only users having a direct link can access it.

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.

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:

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