Skip to main content
Optimization Protection

Request a cryptogram

A cryptogram is generated and used during payment authorization requests as proof of token validation for card transactions requiring online authorization. In this guide, you will learn how to:

  • Implement cryptogram data requirements depending on the card company 
  • Request a cryptogram

Before you begin

Use the following table to learn more about the required fields and values that cryptograms must contain for each card company.

Required fields and values for cryptograms by card brand
API field Visa Mastercard American Express
tokenCryptogramType Token authentication verification value (TAVV)
Dynamic token verification value (DTVV)		 Universal cardholder authentication field (UCAF) Dynamic card security code (DCSC)
randomNumber N/A Required N/A
amount N/A N/A Required
transactionType Required N/A N/A
initiatedBy Required N/A N/A
electronicCommerceIndicator Required Required Required
tokenAuthenticationValue Required Required Required
Tip

Cryptograms are to be used one time only for authorizations. Attempting to re-use a cryptogram will result in an authorization decline from the card company.

Request a cryptogram

Request a cryptogram using a POST call on the /cryptograms endpoint, using either the tokenNumber or tokenReferenceIdentifier field. The response from this API call can contain updated values of the token number or its expiration. You must update your records to ensure that you have the latest information.

HTTP method: POST
Endpoint: /cryptograms
Card company: Visa

Json
{
    "paymentOrder": {
        "amounts": {
            "amount": 1234,
            "currency": "USD"
        },
        "device": {
            "deviceType": "PHONE",
            "deviceIPAddress": "192.168.1.78",
            "deviceLocale": "en-US",
            "deviceLatLong": "40, -73",
            "deviceMake": "Samsung",
            "deviceOS": "ANDROID",
            "deviceOsVersion": "12.0",
            "digitalDeviceIdentifier": "ahd896384d",
            "deviceGeoLocationCaptureTimestamp": "2021-09-08T21:01:20.945Z",
            "deviceName": "Samsung_Android",
            "walletId": "123"
        },
        "initiatedBy": "CARDHOLDER",
        "transactionType": "ECOMMERCE"
    },
    "paymentInstrument": {
        "accountholderName": "Jane Doe",
        "tokenReferenceIdentifier": "205c9a37-ae4a-4cb5-8c9a-75de746500b5",
        "tokenNumber": "XXXXXXXXXXXX1111",
        "electronicCommerceIndicator": "02",
        "expiry": {
            "month": 12,
            "year": 2022
        },
        "tokenAuthenticationValue": "AgAAABBBBq1IZrIDlcLmQD4AAAA=",
        "tokenType": "NETWORK"
    }
}

Response:

Json
{
    "identifier": "f47eb287-f561-4493-921f-ebec52453797",
    "timestamp": "2021-09-15T19:43:59.856",
    "paymentInstrument": {
        "accountholderName": "Jane Doe",
        "tokenReferenceIdentifier": "205c9a37-ae4a-4cb5-8c9a-75de746500b5",
        "tokenNumber": "XXXXXXXXXXXXX1111",
        "electronicCommerceIndicator": "02",
        "expiry": {
            "month": 12,
            "year": 2022
        },
        "tokenAuthenticationValue": "AgAAABBBBq1IZrIDlcLmQD4AAAA=",
        "tokenType": "NETWORK"
    },
    "paymentOrder": {
        "amounts": {
            "amount": 1234,
            "currency": "USD"
        },
        "device": {
            "deviceType": "PHONE",
            "deviceIPAddress": "192.168.1.78",
            "deviceLocale": "en-US",
            "deviceLatLong": "40, -73",
            "deviceMake": "Samsung",
            "deviceOS": "ANDROID",
            "deviceOsVersion": "12.0",
            "digitalDeviceIdentifier": "ahd896384d",
            "deviceGeoLocationCaptureTimestamp": "2021-09-08T21:01:20.945Z",
            "deviceName": "Samsung_Android",
            "walletId": "123"
        },
        "initiatedBy": "CARDHOLDER",
        "transactionType": "ECOMMERCE"
    },
    "requestIdentifier": "1162bba1-d14e-4e49-b870-0d30d599245f",
    "responseStatus": "SUCCESS",
    "responseCode": "ACCEPTED",
    "responseMessage": "The request is well received."
}