Integrate the Payment Isolation Gateway Interface

A Payment Isolation Gateway Interface (PIGI) is the UI a customer uses to input their payment information and add a payment to an order. PIGI was created to isolate customer payment information from everything else that could be happening during a checkout experience to increase security involving the customer’s payment information.

Your store creates and updates an order using the Checkout Backend API. After the order is created, display PIGI in an <iframe> tag to allow the customer to input their payment information. Use the Window.postMessage() method to send actions to PIGI, and PIGI responds in a similar manner.

The following image shows an example of PIGI in a user interface:

Getting the URL for PIGI

In order to embed the PIGI in a page, create an <iframe> tag. Make a call to the Checkout Frontend API within the src attribute of this tag.

You need the following information in order to retrieve the PIGI and load it into the <iframe>:

• shop_identifier — Your store's shop identifier. Retrieved by calling the Get Shop Info endpoint.
• public_order_id — The ID of order. Retrieved by calling the Initialize Order endpoint.
• jwt — The JSON Web Token of the order. Retrieved by calling the Initialize Order endpoint or the Resume Order endpoint if the JWT expires.

The following snippet shows how to use these parameters in an <iframe> tag to load the PIGI. Replace the variables (surrounded by brackets) with your own store and order information.

<iframe
  id="PIGI"
  src="https://api.boldcommerce.com/checkout/storefront/{shop_identifier}/{public_order_id}/payments/iframe?token={jwt}"
/>

Sending Actions to PIGI

PIGI uses Window.postMessage() to communicate between the <iframe> window and its parent.

The following snippet shows an example of sending an action to PIGI:

const iframeElement = document.querySelector("iframe#PIGI");
const iframeWindow = iframeElement.contentWindow;
const action = { actionType: "PIGI_ADD_PAYMENT" };
iframeWindow.postMessage(action, "*");

For a list of actions that can be sent to PIGI, refer to the PIGI API Reference.

Receiving Responses from PIGI

PIGI responds to actions in a similar fashion to how actions are sent to PIGI. For example, in response to the actionType of PIGI_ADD_PAYMENT, PIGI responds with a responseType of PIGI_ADD_PAYMENT along with a payload.

The following snippet shows an example of listening for a response from PIGI:

window.addEventListener("message", ({ data }) => {
  const type = data.responseType;

  if (type) {
    switch (type) {
      case "PIGI_INITIALIZED":
        initCallback(data.payload);
        break;
      case "PIGI_REFRESH_ORDER":
        refreshOrderCallback(data.payload);
        break;
      case "PIGI_ADD_PAYMENT":
        addPaymentCallback(data.payload);
        break;
    }
  }
});

For a list of responses that can be received from PIGI, refer to the PIGI API Reference.

Handling Strong Customer Authentication (SCA)

If the merchant and customer are both located in Europe, you may be required to complete additional verification of the customer's identity to comply with Strong Customer Authentication (SCA). Bold completes this authentication using 3D Secure (3DS) technology, which is displayed within the PIGI iframe.

The following steps outline the process of successfully handling SCA on an order:

1. The frontend calls the Process Order endpoint and receives a 202 error with a request body of {"handleSCA": true}.
2. The frontend uses the PIGI API to send a PIGI_HANDLE_SCA action to PIGI.
3. PIGI uses 3D Secure (3DS) to prompt the customer to verify their identity.
4. PIGI responds to the frontend with a PIGI_HANDLE_SCA response and a request body that contains a "step" value of "DISPLAYED". The frontend resizes the PIGI iframe to properly display the 3DS screen.
5. The customer authenticates their identity.
6. PIGI responds to the frontend with a PIGI_HANDLE_SCA response and a request body that contains a "step" value of "COMPLETED".
7. The frontend retries the Process Order endpoint.

Refer to the PIGI API reference for more information and best practices on handling the responses from PIGI.