Skip to main content

PCI Engagement Notification

Overview​

The PCI Engagement Notification system provides alerts when a user or agent enters or exits a PCI data collection screen. This allows merchants and integrated systems to be aware of when sensitive information is being handled. A PCI Flow (or PCI data collection screen) is any user interface designed to collect sensitive payment details, such as credit card or bank account information. When a user interacts with these forms, the onEvent callback is triggered, signaling to the integrated system that sensitive information is being handled.

Supported Experiences​

Usage​

The implementation for receiving PCI notifications depends on your integration type.

Embedded Experience​

To receive PCI notifications in an embedded environment, you must pass a callback function to the onEvent handler during initialization. This function will be invoked whenever the status of the PCI session changes, specifically with a SESSION_CONTEXT_UPDATED event. For more details, please see the Embedded Environment onEvent section. When a user enters or exits a PCI form, the onEvent callback is triggered with a SESSION_CONTEXT_UPDATED event. The payload of this event contains the status of the PCI session, which your application can use to take appropriate action.

Hosted Experience​

For the hosted experience, PCI status updates are available through the GET /sessions/{sessionId} API endpoint. You must poll this endpoint periodically to retrieve the current session state.

The JSON response from this API call will contain the sessionContext object. By inspecting the pci.active property within this object, you can determine if the user is currently interacting with a sensitive payment form.

Interpreting the PCI Status Data​

Whether you receive the data via the onEvent callback (Embedded) or by polling the GET /sessions/{sessionId} API (Hosted), the structure for communicating the PCI status remains the same.

Within the event's data object, the sessionContext.pci.active property indicates the current state:

  • sessionContext.pci.active = true This means the user has entered the PCI flow.
  • sessionContext.pci.active = false This means the user has exited the PCI flow.
info

In Embedded integration, treat session completion (onSuccess/onError) as the point when PCI is no longer active, since the user has already exited the PCI-sensitive forms. PCI status changes are communicated via the onEvent callback using the SESSION_CONTEXT_UPDATED event.

Example Notification Payloads​

The sessionContext object containing the PCI status will appear as follows.

  • In an embedded integration, this is found within the data object of the SESSION_CONTEXT_UPDATED event.
  • In a hosted integration, this is part of the JSON response from the GET /sessions/{sessionId} API endpoint.

Notification for Entry into a PCI flow​

This event is sent when a user navigates to a screen to input card or bank account details.

{
  "title": "SESSION_CONTEXT_UPDATED",
  "data": {
    "sessionContext": {
      "pci": {
        "active": true
      }
    }
  }
}

Notification for Exit from a PCI flow​

This event is sent when the user navigates away from the card or bank account entry screen.

{
  "title": "SESSION_CONTEXT_UPDATED",
  "data": {
    "sessionContext": {
      "pci": {
        "active": false
      }
    }
  }
}

Things to Keep in Mind​

  • Compatible with all supported payment methods (card, bank account)