Skip to main content

Capture Context

This page contains the information you need to request the capture context using the sessions API.

The capture context request contains all of the merchant-specific parameters that configure the frontend JavaScript library for your payment experience.

The capture context is a signed JSON Web Token (JWT) containing this information:

  • Merchant-specific parameters that dictate the customer payment experience for the current payment transaction.
  • A one-time public key that secures the information flow during the current payment transaction.

The capture context request includes these elements:

  • allowedCardNetworks
  • allowedPaymentTypes
  • clientVersion
  • targetOrigins

For information about JSON Web Tokens, see JSON Web Tokens.

These features are supported with Click to Pay:

allowedCardNetworks

array · Optional

Use the allowedCardNetworks field to define the card types.

These card networks are available for card entry:

  • American Express (supported on Click to Pay)
  • Carnet (cybs, vas, and bofa only)
  • Cartes Bancaires (cybs, vas, and bofa only)
  • China UnionPay (cybs, vas, and bofa only)
  • Diners Club (cybs, vas, Barclays, and bofa only)
  • Discover (cybs, vas, Barclays, and bofa only)
  • EFTPOS (cybs, vas, and bofa only)
  • ELO (cybs, vas, and bofa only)
  • Jaywan (cybs and vas only)
  • JCB (cybs, vas, bofa, and nab only)
  • JCrew (cybs, vas, and bofa only)
  • KCP (cybs, vas, and bofa only)
  • mada (cybs, vas, and bofa only)
  • Maestro (cybs, vas, Barclays, and bofa only)
  • Mastercard (supported on Click to Pay)
  • Meeza (cybs, vas, bofa, and nab only)
  • PayPak (cybs, vas, and bofa only)
  • UATP (cybs, vas, and bofa only)
  • Visa (supported on Click to Pay)

To support dual-branded or co-badged cards, you must list your supported card type values for the allowedCardNetworks field based on your preference for processing card numbers. For example, if a card is dual-branded as Visa and Cartes Bancaires, and Cartes Bancaires is listed first, the card type is set to Cartes Bancaires after the card number is entered in your Unified Checkout card collection form. For information about dual-branded or co-badged cards, see Dual-Branded and Co-Badged Card Support.

allowedPaymentTypes

array · Required

You can specify the type of Unified Checkout digital payment methods that you want to accept in the capture context.

Use the allowedPaymentTypes field to define the payment type:

  • CLICKTOPAY
  • PANENTRY

Click to Pay accepts American Express, Mastercard, and Visa for saved cards. Visa and Mastercard tokenize payment credentials using network tokenization for all Click to Pay requests. Click to Pay uses Click to Pay Token Requester IDs (TRIDs) rather than your existing TRIDs to generate network tokens.

For more information about enabling and managing Click to Pay, see Digital Wallets.

appearance

object · Optional

Click to Pay Drop-In UI supports appearance customization using the appearance field object. You can customize the theme, button configuration, color styling, input states, and typography. All customization fields are optional and can be configured in the API in the appearance.variables field object. For a complete list of customizable fields, see Customization Matrix.

This is an example JSON configuration:

{  "appearance": {    "theme": "LIGHT",    "buttonType": "CHECKOUT",    "variables": {      "backgroundColor": "#FFFFFF",      "textColor": "#000000",      "headerBackground": "#1A237E",      "headerForeground": "#FFFFFF",      "inputBackground": "#FAFAFA",      "buttonBackground": "#E0E0E0",      "buttonForeground": "#333333",      "fontFamily": "Roboto Slab, serif"    }  }}

This is an example sessions capture context request with UI/UX customization:

{  "targetOrigins": [    "https://yourCheckoutPage.com"  ],  "allowedCardNetworks": [    "VISA",    "MASTERCARD",    "AMEX"  ],  "allowedPaymentTypes": [    "CLICKTOPAY"  ],  "appearance": {    "variables": {      "backgroundColor": "#FFFFFF",      "textColor": "#1A1A1A",      "headerBackground": "#0A3450",      "headerForeground": "#FFFFFF",      "headerAvatarBackgroundColor": "#E6EEF8",      "headerAvatarForegroundColor": "#0A2540",      "inputBackground": "#FFFFFF",      "inputColor": "#1A1A1A",      "inputPlaceholderColor": "#6B7280",      "inputBorderColor": "#D1D5DB",      "inputBorderStyle": "solid",      "inputBorderRadius": "6px",      "buttonBackground": "#2563EB",      "buttonForeground": "#FFFFFF",      "buttonShape": "rect",      "buttonBorderColor": "#2563EB",      "buttonBorderStyle": "solid",      "buttonBorderRadius": "8px",      "fontFamily": "Inter, Arial, sans-serif",      "borderRadius": "8px",      "paymentSelectionBackground": "#F9FAFB"    }  },  "country": "US",  "locale": "en_US",  "captureMandate": {    "billingType": "FULL",    "requestEmail": true,    "requestPhone": true,    "requestShipping": true,    "shipToCountries": [      "US",      "GB"    ],    "showAcceptedNetworkIcons": true  },  "data": {    "orderInformation": {      "amountDetails": {        "totalAmount": "21.00",        "currency": "USD"      }    }  }}

buttonType

string · Optional

When Unified Checkout loads, the payment buttons displayed are based on what you include in the allowedPaymentTypes object in the capture context. Unified Checkout enables you to customize the text on the payment buttons. You can do this by setting the buttonType field object in the capture context to one of these values:

  • ADD_CARD
  • CARD_PAYMENT
  • CHECKOUT_AND_CONTINUE
  • DEBIT_CREDIT
  • DONATE
  • PAY
  • PAY_WITH_CARD
  • SUBSCRIBE_WITH_CARD

If you do not include the buttonType field in your request, the payment button text defaults to Checkout with card. For example:

Use the buttonType field to customize the text on payment buttons. This table describes the button text options:

buttonType ValueButton Display Text
ADD_CARDAdd card
CARD_PAYMENTCard payment
CHECKOUT_AND_CONTINUECheckout and continue
DEBIT_CREDITDebit or credit
DONATEDonate
PAYPay
PAY_WITH_CARDPay with card
SUBSCRIBE_WITH_CARDSubscribe with card

When you do not include this field in your request, the default button text is Checkout with card.

captureMandate

object · Optional

The capture mandate enables you to define which fields are captured within Unified Checkout. You must include the fields and set the values in the capture context based on the information that you want Unified Checkout to collect. This enables the cardholder to review and edit their details where the UI includes these fields. When the UI is used to capture cardholder information, all captured information is available within the payment details API response. When you want the cardholder to review existing address data, you can include the known customer data in the capture context and this information is pre-filled in the Unified Checkout UI. For information about the payment details API, see Get Payment Details.

captureMandate.billingType

string · Optional

PARTIAL: Only the billing postal code and billing country are collected in the UI. Set to this value when you use relaxed address verification services (AVS). This includes markets where postal code and billing country are enough for successful payment processing.

NONE: No fields are shown in the UI to capture cardholder billing details. If you are using the Complete Mandate, you must provide billing details in the capture context. All information that is collected from these fields is tokenized in the transient token and sent for payment processing. For information about which fields are required for payment processing, see the Payments Developer Guide.

FULL: These fields are shown in the UI to capture cardholder billing details. When you include the billing details in the capture context, these details are pre-filled in the Unified Checkout UI. All information that is collected from these fields are tokenized in the transient token and sent for payment processing where the Complete Mandate is used.

captureMandate.comboCard

boolean · Optional

Availability: Applies to cybs, vas, and bofa. Does not apply to , CLIQ, or nab.

A combo card is a single card in Brazil that functions as both a debit and a credit card. Unified Checkout enables the cardholder to choose whether to pay for a transaction using a debit or credit card. The cardholder can choose the card that they want to use when they enter their card details or when they choose a stored Visa card from their Click to Pay wallet during checkout. While in the card details section of the payment form, the cardholder is prompted for a debit or credit card. Credit is the default option.

To enable combo cards during checkout, you must include the comboCard field in your capture context request and set the field value to true. When the comboCard field value is set to true, the option to use a debit or credit card appears for all Visa cards that are entered in Unified Checkout and for all cards that are already stored in Click to Pay. If you do not want to offer a combo card at checkout, do not include the comboCard field in your capture context request:

"captureMandate" : {  "comboCard": true}

captureMandate.CPF

object · Optional

Availability: Applies to cybs, vas, bofa, and nab. Does not apply to or CLIQ.

The Cadastro de Pessoas Físicas (CPF) Brazilian tax ID feature is for customers in Brazil and provides your customers with a way to include their Consumer National Identifier when it is requested at checkout. Include this field in the capture context to display this field within the flow for manual card entry and Click to Pay transactions:

"captureMandate" : {    "CPF": {        "required": true    }}

captureMandate.requestEmail

boolean · Optional

false: No email address is shown in the UI. If you are using Click to Pay, this email address is used to find the cardholder's Click to Pay account and it appears in the UI when requestEmail is set to false.

true: The email address is shown and captured in the UI. If you are using Click to Pay, this email address is used to find the cardholder's Click to Pay account.

captureMandate.requestPhone

boolean · Optional

false: No phone number is shown or captured in the UI.

true: The phone number is shown and captured in the UI.

captureMandate.requestSaveCredentials

boolean · Optional

This feature enables you to display a consent option in the Unified Checkout UI for the cardholder to save their payment details for future use.

When you use this field without using the complete mandate, the transient token payload includes the consumerPreference.saveCard field with the value set to true when the cardholder has checked to save the payment information for future purchases:

"captureMandate" : {  "requestSaveCredentials": true}

captureMandate.requestShipping

boolean · Optional

false: No shipping information is captured in the UI. When shipping details are required for payment processing and are used for follow-on services such as Decision Manager, you can include these fields in the capture context. These details are tokenized and passed through.

true: Shipping fields are shown in the UI and are collected by Unified Checkout. When you include the shipping details in the capture context, the information appears prefilled in the UI.

captureMandate.shipToCountries

array · Optional

When the requestShipping field is set to true, only the countries that are included in this field can be selected by the cardholder for their shipping address.

captureMandate.showConfirmationStep

boolean · Optional

When showConfirmationStep is set to false, you can remove the final summary confirmation screens from the checkout experience. When the UI displays cardholder data, the cardholder can review and, if necessary, edit their payment details before checkout is complete.

{  "captureMandate": {    "showConfirmationStep": false  }}

paymentConfigurations.CLICKTOPAY.autoCheckEnrollment

boolean · Optional

Availability: Applies to cybs, vas, bofa, and nab. Does not apply to or CLIQ.

You can have the Click to Pay box pre-checked when a user is manually entering their card details and Click to Pay is enabled. The customer can uncheck the box if necessary, which means the request is processed as a one-time manual PAN transaction. This is available when you set the billingType field to PARTIAL or FULL in the capture context. This ensures that the customer's billing country can be validated in the UI.

Click to Pay enrollment pre-check is available in these countries:

  • Argentina
  • Brazil
  • Chile
  • Colombia
  • Kuwait
  • Mexico
  • Peru
  • Qatar
  • Saudi Arabia
  • South Africa
  • Ukraine
  • United Arab Emirates
"paymentConfigurations": {  "CLICKTOPAY": {    "autoCheckEnrollment": true  }}

targetOrigins

array · Required

The target origin is defined by the scheme (protocol), hostname (domain), and port number (if used).

You must use the https:// protocol. Sub domains must also be included in the target origin.

Any valid top-level domains, such as .com, .co.uk, and .gov.br, are supported. Wildcards are not supported.

For example, if you are launching Unified Checkout on example.com, the target origin could be any of these:

When you use Unified Checkout in an iframe, you must include the domain for the URL that loads the iframe and the iframe URL in the targetOrigins field.

transientTokenResponseOptions.includeCardPrefix

boolean · Optional

You can control the length of the card number prefix to be received in the response to the capture context /sessions request:

  • Six digits
  • Eight digits
  • No prefix

To specify your preferred card number prefix length, include or exclude the transientTokenResponseOptions.includeCardPrefix field in the capture context /sessions request.

To receive a six-digit card number prefix in the response: Do not include the transientTokenResponseOptions.includeCardPrefix field in the capture context /sessions request.

This example shows how the transient token response returns a six-digit card number prefix 411111:

"maskedValue" : "XXXXXXXXXXXX1111","bin" : "411111"

To receive an eight-digit card number prefix in the response: Include the transientTokenResponseOptions.includeCardPrefix field in the capture context request, and set the value to true.

This example shows how the transient token response returns an eight-digit card prefix 41111102:

"maskedValue" : "XXXXXXXXXXXX1111","prefix" : "41111102"

To not receive a card number prefix in the response: Include the transientTokenResponseOptions.includeCardPrefix field in the capture context request, and set the value to false.

This example shows how the transient token response returns a card number without a card number prefix:

"maskedValue" : "XXXXXXXXXXXX1111"

Best practice: If your application does not require card number prefix information for routing or identification, recommends that you include the transientTokenResponseOptions.includeCardPrefix field in the capture context request and set its value to false. Doing so limits the exposure of payment data to only what is necessary for your processing needs.

For more information about PCI DSS, see Frequently Asked Questions on the PCI Security Standards Council site.

Email Autolookup

When you include Click to Pay as an allowedPaymentType, an automatic email lookup occurs when an email address is included in the capture context request in the data.billTo.email field. If the user has a Click to Pay account but is not on a recognized device, a one-time password (OTP) screen appears and the user is prompted to enter their OTP. If the user does not have a Click to Pay account, the user must enter their card information manually. The user has the option to create a Click to Pay account.

Mobile as Identity for Click to Pay

Click to Pay supports mobile numbers as a way to identify a user. This enables cardholders to use their mobile number instead of their email address in certain markets for Visa and Mastercard transactions.

When the requestEmail field is set to false and the requestPhone field is set to true, the cardholder is identified using the provided mobile number. When the requestEmail field is set to true and the requestPhone field is set to false, the cardholder is identified using the provided email address. When the requestEmail field is set to true and the requestPhone field is also set to true, the cardholder is identified using the provided email address first and then the mobile number if there is no match.

Next Steps

Last published: September 29, 2026