On This Page

Server-Side Set Up

This section contains the information you need to set up your server. Initializing
Unified Checkout
 within your webpage begins with a server-to-server call to the sessions API. This step authenticates your merchant credentials, and establishes how the
Unified Checkout
 frontend components will function. The sessions API request contains parameters that define how
Unified Checkout
 performs.
The server-side component provides this information:
  • A transaction-specific public key is used by the customer's browser to protect the transaction.
  • An authenticated context description package that manages the payment experience on the client side. It includes available payment options such as card networks, payment interface styling, and payment methods.
The functions are compiled in a JSON Web Token (JWT) object referred to as the
capture context
. For information JSON Web Tokens, see JSON Web Tokens.

Capture Context

The capture context request is a signed JSON Web Token (JWT) that includes all of the merchant-specific parameters. This request tells the frontend JavaScript library how to behave within your payment experience. The request provides authentication, one-time keys, the target origin to the
Unified Checkout
 integration in addition to allowed card networks and payment types. The capture context request includes these elements:
  • Allowed card networks
  • Allowed payment types
  • Client version
  • Target origin
  • Include card prefix
For information on JSON Web Tokens, see JSON Web Tokens.
Target Origin
The target origin is defined by the scheme (protocol), host name (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 domain is supported, such as .com, .co.uk, and.gov.br. Wildcards are not supported.
For example, if you are launching
Unified Checkout
 on example.com, the target origin could be any of these values:
You can define the payment cards and digital payments that you want to accept in the capture context.
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
  • JCB
  • JCrew
  • Mada
  • Maestro
  • Mastercard
  • Meeza
  • Visa
To support dual-branded or co-badged cards, you must list your supported card types 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 Support for Dual-Branded Cards.
IMPORTANT
Click to Pay
 supports 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 the your existing TRIDs.
IMPORTANT
Unified Checkout
 does not process transactions for cards that do not have a card verification number (CVN) and expiration date. Most China UnionPay debit and credit cards issued before 2016 do not have a CVN and expiration date. You must decide whether you will require the CVN.
Allowed Payment Types
Use the
allowedPaymentTypes
 field to define the accepted digital payment methods:
  • APPLEPAY
  • CHECK
  • CLICKTOPAY
  • GOOGLEPAY
  • PANENTRY
IMPORTANT
You can accept Apple Pay, Google Pay, and
eCheck
 digital payment methods in
Unified Checkout
 without requiring card payments. To accept Apple Pay, Google Pay, and
eCheck
 digital payment methods without requiring card payments, include these digital payment methods in the
allowedPaymentTypes
 field and exclude
PANENTRY
.
Include Card Prefix
You can control the length of the card number prefix to be received in the response to the capture context request:
  • 6 digits
  • 8 digits
  • no prefix at all
To specify your preferred card number prefix length, include or exclude the
transientTokenResponseOptions.includeCardPrefix
 field in the capture context request.
If you want to receive a 6-digit card number prefix in the response
  • Do not
     include the
    transientTokenResponseOptions.includeCardPrefix
     field in the capture context request.
  • This example shows how a 6-digit card number prefix
    411111
     is returned in the transient token response:
    "maskedValue" : "XXXXXXXXXXXX1111”,
"bin" : "411111"
If you want to receive an 8-digit card number prefix in the response
  • Include the
    transientTokenResponseOptions.includeCardPrefix
     field in the capture context request, and set the value to
    true
    .
    IMPORTANT
    Per PCI DSS requirements, this requirement applies only to card numbers longer than 15 digits and for Discover, JCB, Mastercard, UnionPay, and Visa brands.
    • If the card type entered is not part of these brands, a 6-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 8-digit card number prefix is returned.
  • This example shows how an 8-digit card prefix
    41111102
     is returned in the transient token response:
    "maskedValue" : "XXXXXXXXXXXX1111”,
"prefix" : "41111102"
If you do not want to 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 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 purposes,
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.
Use the
targetOrigins
 and the
allowedPaymentTypes
 fields to define the target origin and the accepted digital payment methods in your capture context. For example:
{
  "targetOrigins" : [ "https://www.test.com" ],
  "clientVersion" : "0.23",
  "allowedCardNetworks" : [ "VISA", "MASTERCARD", "AMEX" ],
  "allowedPaymentTypes" : [ "PANENTRY", "CLICKTOPAY", "GOOGLEPAY" ],
  "country" : "US",
  "locale" : "en_US",
  "captureMandate" : {
    "billingType" : "FULL",
    "requestEmail" : true,
    "requestPhone" : true,
    "requestShipping" : true,
    "shipToCountries" : [ "US", "GB" ],
    "showAcceptedNetworkIcons" : true
  },
  "orderInformation" : {
    "amountDetails" : {
      "totalAmount" : "1.01",
      "currency" : "USD"
    }
  }
}
This diagram shows how elements of the capture context request appear in the card entry form.

Figure:

Anatomy of a Manual Card Entry Form
Image of the capture context request code and how it appears in the entry form elements.
For more information on requesting the capture context, see Capture Context API.