On This Page

Transient Tokens

The response to a successful customer interaction with
Unified Checkout
 is a transient token. This is returned in the response from the
unifiedPayment.show()
 function. The transient token is a reference to the payment data collected on your behalf. Tokens allow secure card payments to occur without risk of exposure to sensitive payment information. The transient token is a short-term token that expires after 15 minutes. This reduces your PCI burden/responsibility and ensures that sensitive information is not exposed to your back-end systems.
Transient tokens can be included requests sent to the Payment Details and Payment Credentials APIs in exchange for the customer payment data that is collected. This data can include the payment account number (PAN) or tokenized credentials.

Transient Token Format

The transient token is issued as a JSON Web Token (JWT) (RFC 7519). For information on JSON Web Tokens, see JSON Web Tokens.
The payload portion of the token is a Base64-encoded JSON string and contains various claims.

Example: Transient Token Format

Transient Token Payload
{
  "iss": "Flex/00",
  "exp": 1706910242,
  "type": "gda-0.9.0",
  "iat": 1706909347,
  "jti": "1D1I2O2CSTMW3UIXOKEQFI4OQX1L7CMSKDE3LJ8B5DVZ6WBJGKLQ65BD6222D426",
  "metadata": {
    "consumerPreference": {
      "saveCard": true
    },
    "tokenizedCard": {
      "card": {
        "maskedValue": "XXXXXXXXXXXX9876",
        "prefix": "123456",
        "expirationMonth": "MM",
        "expirationYear": "YYYY"
      }
    }
  },
  "content": {
    "orderInformation": {
       "billTo" : {
        // Empty fields present within this node indicate which fields were captured by
        // the application without exposing you to personally identifiable information
        // directly.
      },
      "amountDetails" : {
        // Empty fields present within this node indicate which fields were captured by
        // the application without exposing you to personally identifiable information
        // directly.
      },
      "shipTo" : {
        // Empty fields present within this node indicate which fields were captured by
        // the application without exposing you to personally identifiable information
        // directly.
      }
    },
    "paymentInformation": {
      "card": {
        "expirationYear": {
          "value": "2028"
        },
        "number": {
          "maskedValue": "XXXXXXXXXXXX1111",
          "bin": "411111"
        },
        "securityCode": {},
        "expirationMonth": {
          "value": "06"
        },
        "type": {
          "value": "001"
        }
      }
    }
  }
}
PAN BIN in
metadata
 Object
The
cardDetails
 object, including the PAN BIN, is included in the transient token
metadata
 when a
Click to Pay
 network token is used as a payment method. This allows you to display information about the card on invoices and see the BIN details that are linked to the underlying card.
"metadata": {
  "cardDetails": {
    "suffix": "9876",
    "prefix": "123456",
    "expirationMonth": "MM",
    "expirationYear": "YYYY"
  }
}
Authentication Status in
metadata
 Object
The
authenticationStatus
 is included in the
metadata
 and enables you to determine if the payload is fully authenticated or if
3-D Secure
 must be completed in a follow-on action. 
"metadata": {
  "authenticationStatus": "AUTHENTICATED"
  }
}

Token Verification

When you receive the transient token, you should cryptographically verify its integrity using the public key embedded within the capture context. Doing so verifies that
Cybersource
 issued the token and that the data has not been tampered with in transit. Verifying the transient token JWT involves verifying the signature and various claims within the token. Programming languages each have their own specific libraries to assist.
For an example in Java, see: Java Example in Github.

Support for Dual-Branded Cards

Unified Checkout
 supports dual-branded cards. To utilize this feature, you must include the card networks that have overlapping BIN ranges in the capture context request. For example:
"allowedCardNetworks": ["VISA", "MASTERCARD", "AMEX", "CARTESBANCAIRES"]
When a card number within an overlapping BIN range is entered, the network that is listed first in the value array for the
allowedCardNetworks
 field is used. For example, if the card number 403550XXXXXXXXXX is entered, the payment network is Visa.
During the transaction, the card type is populated with the first network in the list and the
detectedCardTypes
 field includes all of the detected card types in the transient token.
The
detectedCardTypes
 field will only be returned in the transient token response when more than one card type is detected.