On This Page
FILTER BY TAG

Capture Context API

The capture context request contains all of the merchant-specific parameters that tell the front-end JavaScript library what to do within 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 fields:
  • allowedCardNetworks
  • allowedPaymentTypes
  • clientVersion
  • targetOrigins
For information on JSON Web Tokens, see JSON Web Tokens.
Allowed Card Networks
Use the
allowedCardNetworks
 field to define the card types.
These card networks are available for card entry:
  • American Express
  • Cartes Bancaires
  • Carnet
  • China UnionPay
  • Diners Club
  • Discover
  • EFTPOS
  • ELO
  • Jaywan
  • JCB
  • JCrew
  • KCP
  • mada
  • Maestro
  • Mastercard
  • Meeza
  • PayPak
  • UATP
  • Visa
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 on dual-branded or co-badged cards, see Dual-Branded Cards.
IMPORTANT
Some card types, such as KCP and UATP, do not have security codes (CVV or CVN). If you include only card types that do not have security codes in the
allowedCardNetworks
 field,
Unified Checkout
 does not display the security code field in the UI.
If you include card types that do not have security codes and cards types that do have security codes in the
allowedCardNetworks
 field,
Unified Checkout
 displays the security code field in the UI. The field is disabled in the UI when the cardholder enters a card number for a card type with no security code.
Target Origin
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 the following:
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.
Allowed Payment Types
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:
  • AFTERPAY
  • APPLEPAY
  • BANCONTACT
  • CHECK
  • CLICKTOPAY
  • DRAGONPAY
  • GOOGLEPAY
  • IDEAL
  • KONBINI
  • MULTIBANCO
  • MYBANK
  • P24
  • PANENTRY
  • PAZE
  • TINKPAYBYBANK
IMPORTANT
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 on enabling and managing these digital payment methods, see these topics:
Capture Mandate
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 Payment Details API.
Capture Mandate Field Values and Outcomes
Capture Mandate Field
Value
Outcome
billingType
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.
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.
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.
requestEmail
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.
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
.
requestPhone
true
The phone number is shown and captured in the UI.
false
No phone number is shown or captured in the UI.
requestShipping
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.
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.
shipToCountries
ISO country code
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.
Complete Mandate
The complete mandate feature provides service orchestration within
Unified Checkout
 and simplifies your integration. Service orchestration enables
Unified Checkout
 to orchestrate services on your behalf. The complete mandate feature provides instructions to the
unifiedPayment.complete()
 method in the JavaScript. You must include both the
unifiedPayment.complete()
 object in the Javascript and the
completeMandate
 field object in your capture context to enable
Unified Checkout
 to initiate services on your behalf from the browser.
IMPORTANT
If you are updating an existing
Unified Checkout
 configuration to use the complete mandate, you must update your JavaScript to include the
unifedPayment.complete()
 function.
IMPORTANT
When the
billingType
 field is set to
NONE
 you must include the required fields within the capture context request to ensure that the required fields are included for payment processing. For information about the fields that are required for payment services, see the Payments Developer Guide.
The complete mandate feature is defined by these fields:
  • completeMandate.type
    : This field is required to run the complete mandate and is used to indicate how a payment should be processed.
    Possible values:
    • AUTH
      : Authorize the payment and capture the funds at a later date.
    • CAPTURE
      : Perform a sale. A sale is a combined authorization and capture in a single request.
    • PREFER_AUTH
      : Perform an authorization if possible. If a payment method requires the funds to be captured immediately, then
      Unified Checkout
       captures the payment.
  • completeMandate.decisionManager
    : This field determines whether
    Decision Manager
     is run. Set this field to
    true
     and include
    completeMandate.type
     in your request to run
    Decision Manager
     and device fingerprinting services. When
    Decision Manager
     runs, it uses the associated
    Decision Manager
     configuration based on the merchant ID that is included in the request.
    When this field is set to
    false
     or is not included in the request,
    Decision Manager
     and device fingerprinting services do not run.
  • completeMandate.consumerAuthentication
    : This field determines whether
    Payer Authentication
     should be used. Set this field to
    true
     and include
    completeMandate.type
     in your request to run
    Payer Authentication
    . When this field set to
    true
    ,
    Payer Authentication
     runs. When this field is set to
    false
     or is not included in the request,
    Payer Authentication
     does not run.
    When you use
    Unified Checkout
     with
    Payer Authentication
    , device data is collected through
    Payer Authentication
     setup and
    Unified Checkout
     completes all calls that are associated with
    Payer Authentication
    .
    Unified Checkout
     supports the pass-through fields that are required for
    Payer Authentication
     challenge codes. For information about the required fields, see Unified Checkout Field Reference.
    For information about challenge codes, see
    consumerAuthenticationInformation.challengeCode
     in the REST API Field Reference. Unified Checkout supports
    3-D Secure
     data only when your payment processor supports it. For information see Visa Data Only in the
    Payer Authentication
     Developer Guide
    .
    To test
    Payer Authentication
    , you must use
    Payer Authentication
     test cards. See Test Cases for 3-D Secure 2.x in the
    Payer Authentication
     Developer Guide
    .
    Consumer authentication is available for these card types:
    • American Express
    • Cartes Bancaires
    • China UnionPay
    • Diners Club
    • Discover
    • EFTPOS
    • ELO
    • Jaywan
    • JCB
    • mada
    • Maestro
    • Mastercard
    • Visa
    • Jaywan
    Consumer authentication runs for these payment methods when they are supported in your
    Unified Checkout
     configuration:
    • PANENTRY
    • CLICKTOPAY
       when the transaction is not authenticated with
      Click to Pay
      .
    • GOOGLEPAY
       when the transaction is not authenticated with Google Pay.
    Unified Checkout
     does not attempt to authenticate for
    Click to Pay
     and Google Pay if the transaction has already been authenticated when it is received by
    Unified Checkout
    . For information about testing authentication, see Test Authentication.
  • completeMandate.tms.tokenCreate
    : This field determines if a
    TMS
     token is created for the customer's selected payment method. When this field is set to
    true
    , a token is created. When this field is set to
    false
     or not included in the request, a token is not created.
  • completeMandate.tms.tokenTypes
    : This is an optional field that you can use to indicate the token type for the token that is created. When this field is not included in the request, a token is created based on your
    TMS
     vault configuration. You can set this field to these values:
    • customer
    • instrumentIdentifier
    • paymentInstrument
    • shippingAddress
    If you want
    Unified Checkout
     to capture the cardholder's consent to save the card before a request to create a token is completed, then you must set
    captureMandate.requestSaveCard
     to
    true
    . When this field is set to
    true
    ,
    Unified Checkout
     presents a
    Save card for future payments
     checkbox within the UI and enables the cardholder to give consent. Do not include
    captureMandate.requestSaveCard
     in your request if you have already gained cardholder consent to create a
    TMS
     token or do not require consent.
    This table indicates if a token is created given the requested payment method:
    Payment Method
    Capture Context
    Result
    PAN Entry and
    Click to Pay
    completeMandate.tms.tokenCreate
     =
    true
    TMS
     token is created at the token level(s) specified in the request or based on the default for the token vault.
    completeMandate.tms.tokenCreate
     =
    true
     and
    captureMandate.requestSaveCard
     =
    true
    Cardholder can check
    Save Payment Information
     in
    Unified Checkout
    . The request to create a token is made when the cardholder checks this field in the UI. When it is not checked, ni token is created.
    Apple Pay, Google Pay
    , and Paze
    completeMandate.tms.tokenCreate
     =
    true
    TMS
     token is created at the token level(s) specified in the request or based on the default for the token vault.
    completeMandate.tms.tokenCreate
     =
    true
     and
    captureMandate.requestSaveCard
     =
    true
    Unified Checkout
     cannot obtain consent to create a token and no token is created when the customer completes the payment.
    Echeck
    completeMandate.tms.tokenCreate
     =
    true
    TMS
     token is created at the token level(s) specified in the request or based on the default for the token vault.
    completeMandate.tms.tokenCreate
     =
    true
     and
    captureMandate.requestSaveCard
     =
    true
    Unified Checkout
     cannot obtain consent to create a token and no token is created when the customer completes the payment.
Include Card Prefix
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, follow this step:
Do not
 include the
transientTokenResponseOptions.includeCardPrefix
 field in the capture context
/sessions
 request.
This example shows how a six-digit card number prefix
411111
 is returned in the transient token response:
"maskedValue" : "XXXXXXXXXXXX1111”,
                "bin" : "411111"
To receive an eight-digit card number prefix in the response, follow this step:
Include the
transientTokenResponseOptions.includeCardPrefix
 field in the capture context request, and set the value to
true
.
IMPORTANT
This PCI DSS requirement applies only to card numbers longer than 15 digits and only for Discover,
JCB,
 Mastercard,
UnionPay,
 and Visa brands.
  • If the card type entered is not part of these brands, a six-digit card number prefix is returned instead.
  • If the card type entered is not part of these brands but is
    co-branded
     with these brands, an eight-digit card number prefix is returned.
This example shows how an eight-digit card prefix
41111102
 is returned in the transient token response:
"maskedValue" : "XXXXXXXXXXXX1111”,
                "prefix" : "41111102"
To not receive a card number prefix in the response, follow this step:
Include the
transientTokenResponseOptions.includeCardPrefix
 field in the capture context request, and set the value to
false
.
This example shows how a card number is returned without a card number prefix in the transient token response:
"maskedValue" : "XXXXXXXXXXXX1111"
Best practice:
If your application does not require card number prefix information for routing or identification,
Cybersource
 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.
IMPORTANT
Cybersource
 recommends that you dynamically parse the response for the fields that you are looking for when you integrate with
Cybersource
 APIs.
Cybersource
 may add additional fields in the future.
You must ensure that your integration can handle new fields that are returned in the response. Even though the underlying data structures do not change, you must also ensure that your integration can handle changes to the order in which the data is returned.
Cybersource
 uses semantic versioning practices, which enables you to retain backwards compatibility as new fields are introduced in minor version updates.
RELATED TO THIS PAGE