Skip to main content
The Checkout Experience extension lets you control how shoppers interact during payment — from collecting card credentials to completing 3-D Secure challenges. Commerce delegates these interactions to your service and routes the shopper accordingly.
This extension is mandatory if you require custom shopper interactions.Contact Hellgate Support to enable it for your account.

​
Architecture

Diagram showing the Checkout Experience architecture: Commerce calls your Checkout Experience service, which communicates with the Client Library in the Shopper Experience
Your Checkout Experience service sits between Commerce and the shopper’s client. Two channels connect the components:
  • REST — Commerce calls your service synchronously to open sessions when shopper input is required.
  • Cloud Events — Your service and Commerce exchange results asynchronously via the event-bridge.

​
Payment Session

A Payment Session is triggered when Commerce needs the shopper to provide payment details, such as card credentials. Your service returns a session_key used to initialize the Client Library. Commerce surfaces the requirement as an ACTION_REQUIRED response: 
{
  "processing": {
    "status": "ACTION_REQUIRED",
    "requirement": {
      "action": "SET_PAYMENT_METHOD",
      "message": "Please set the payment method.",
      "options": [
        {
          "library": "CHECKOUT_EXPERIENCE",
          "message": "Initialize the library with this key.",
          "session_key": "<session_key>"
        }
      ]
    }
  }
}
Initialize the Client Library with the session_key. Once the shopper submits their card details, your Checkout Experience sends one of these events to Commerce via the event bridge: See Create Session for the API reference.

​
3-D Secure Session

A 3-D Secure Session is triggered when a payment requires a 3DS challenge. Your service returns a redirect_url and Commerce instructs your client to redirect the shopper. Commerce surfaces the requirement as an ACTION_REQUIRED response: 
{
  "processing": {
    "status": "ACTION_REQUIRED",
    "requirement": {
      "action": "REDIRECT",
      "options": [
        { "url": "https://3ds.processor.example.com/session/abc123" }
      ]
    }
  }
}
Redirect the shopper to the provided URL. After the challenge completes, send a TDSResult event to Commerce via the event bridge. Commerce then confirms the outcome with a CompleteTDSSession event. See Create 3DS Session for the API reference.

​
Lifecycle Events from Commerce

Commerce sends these events across both session types to notify you of state changes: