On This Page

Server-Side Set Up

This section contains the information you need to set up your server. Initializing Unified Click to Pay within your webpage begins with a server-to-server call to the sessions API. This step authenticates your merchant credentials, and establishes how Unified Click to Pay manages your capture context configuration. This includes supported locales, currencies, and country availability. The sessions API request contains parameters that define how Unified Click to Pay performs.

For information about sessions API requests, see Generate Unified Click to Pay Capture Context in the Cybersource API Reference.

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, and payment methods.

The functions are compiled in a JSON Web Token (JWT) object referred to as the capture context
. The header of each JWT header contains a key ID field (

kid

) that references the specific RSA public key that Cybersource used to sign that token. The integrator must retrieve this public key from Cybersource and use it to verify the JWT's signature. If the signature is invalid, the JWT must be rejected. For information about JWTs, JWT validation keys, and API authentication keys, see these topics:

JSON Web Tokens

JWT Validation Keys

API Authentication Keys

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, in addition to allowed card networks and payment types. The capture context, at a minimum, requires these elements:

allowedCardNetworks

amountDetails

billingType

country

currency

data.orderInformation.amountDetails.totalAmount

data.orderInformation.amountDetails.currency

locale

totalAmount

version

Capture Context Example

{
    // -------- REQUIRED VALUES ----------
    "data": {
        "orderInformation": {
            "amountDetails": { 
                "totalAmount": "123.94", 
                "currency": "USD" 
            }
        }
    }, 
    "allowedCardNetworks": [ 
        "VISA",
        "MASTERCARD",
        "AMEX"
    ],
    "billingType": "FULL",
    "country": "US",
    "locale": "en_US",
    "version":"0.6" 
}

Versioning

Unified Checkout uses Semantic Versioning (SemVer). Version numbers use the

MAJOR.MINOR.PATCH

format:

MAJOR
: breaking changes that require code modifications

MINOR
: new features that are backwards compatible

PATCH
: bug fixes and improvements that are backwards compatible

The server controls which SDK version is loaded for each session that you request. When your server creates a session, the response JWT includes a

clientLibrary

field that contains the full URL to the correct version of the SDK. Your server parses the JWT, extracts the URL, and passes it to the frontend to load dynamically.

IMPORTANT

The

clientVersion

field in the session request is optional. When you do not include this field, the server automatically resolves the appropriate version for every session. This ensures that the client-side library and server-side features are compatible.Cybersource recommends that you do not include the

clientVersion

field in your request and that you use the most recent version. When you do this, your integration benefits from new features, payment methods, and improvements and there are no code changes required.

Pin to a Version

If you must set your integration to a specific version, you can set the

clientVersion

field to a

MAJOR

version such as

, or a

MAJOR.MINOR

version such as

1.2

. The server uses the latest compatible patch release within that range. This ensures that you continue to receive security fixes and bug fixes.

IMPORTANT

You cannot pin to a specific patch version (

MAJOR.MINOR.PATCH

). This ensures that all integrations receive critical patches. Cybersource recommends omitting

clientVersion

from your request unless you have a specific need for pinned behavior.

Client Version History

This is a list of client versions and the features included in each version. For more details on specific changes from version to version, see Client Version Changes in the appendix.

IMPORTANT

Cybersource recommends that you use the most recent client version in your integration.

0.10: The SDK supports FIDO/passkey authentication for Mastercard.; payloadTypeIndicatorCheckout
supports a summary payload type.; bindingStatus
is now accurate for Mastercard DCF-less checkout.
0.9: The SDK supports multi-email session handling.; checkout()
no longer throws
SDK_NOT_INITIALIZED
after a
CHANGE_CARD
action code.; dpaTransactionOptions
is now served from the backend for Mastercard DCF-less checkout.; Mastercard 3-D Secure reaches parity with Visa.; dpaTransactionOptions
authentication configuration is unified through session configuration.; getCards()
card objects now include
paymentCardDescriptor
.; checkout()
supports transaction amount and currency updates through
dpaTransactionOptions
.; initialize()
now returns void.; checkout()
supports the
SWITCH_CONSUMER
action code.; The guest card details model supports CPF (Brazilian tax ID).; The decoded checkout response includes
assuranceData
.
0.8: initialize()
no longer double-wraps the JWT.; OTP errors are now thrown instead of returned as an
ERROR
action code.; checkout()
returns a restructured response object.; dpaTransactionOptions
supports
dpaPresentationName
for Mastercard.; checkout()
supports 3-D Secure for Mastercard.
0.7: initialize()
now takes the raw JWT string.; getCards()
no longer throws
ERROR
on the guest flow.; initialize()
failures now include an
error.reason
property.