Get cryptogram

This API call is used to get a cryptogram on behalf of a token that needs to be used for the authorization.

The full flow for generating a cryptogram is defined below. Please note that if no secure server (3D) is involved, steps 1 and 2 can be skipped, and the flow starts at step 3.

info

Also note that cryptograms are used for CIT payment flows only, where the cardholder initiates the payment process.

Notice that there is no liability shifting when using tokens. Liability is only shifted by the rules handled by the secure server. When no secure server is used liability is normally placed on the merchant. Cardtokens advise their clients to contact their connected acquirers for more details about liability and shifting.

Notice in the flow described below, Cardtokens is only involved in the calls inside the red box.

Steps:

1. The integrator communicates with the secure server to authenticate the cardholder. In the case of a challenge, the cardholder must perform identity verification.
2. When the cardholder is authenticated, the authentication data is returned to the integrator (CAVV, AVV).
3. The requester calls the Cardtokens API to generate a cryptogram on behalf of a token.
4. Cardtokens communicate with the card scheme, which owns the network token.
5. Upon validation, the card scheme returns to Cardtokens with a cryptogram.
6. Cardtokens returns to the integrator with the cryptogram received from the card scheme.
7. The integrator performs an authorization request to the connected acquirer.
8. The acquirer returns with an authorization response to the integrator.

Endpoint and method

Method: POST

Endpoint: https://api.cardtokens.io/api/token/{tokenid}/cryptogram

Request parameters

Parameter name	Data type	Description
Reference	String	Required. The order reference used for the purchase.
transactiontype	String	Optional. The transaction type can be one of “ecom”, “recurring”. Default “ecom”
unpredictablenumber	String	Optional. Random number that can be generated by the merchant for use generating the cryptogram (Mastercard only). If this is skipped Cardtokens will generate a random number. Length must be either 0 or 8 and numbers only (0-9).

Response parameters

Parameter name	Data type	Description
cryptogram	String	The cryptogram to be included in the authorization with the acquirer. For Mastercard, this is the de48se43Data. MinLength: 1, maxLength: 32, example: "11223344556677889900112233445566". For Visa, this is the cryptogram from the “Cryptogram Info” structure. Format: Alphabetic, numeric; maximum 28 characters. For the test scheme, the cryptogram is a base64 formatted GUID.
token	String	The major scheme network token generated. Please refer to “Create Token” for details about this field.
expmonth	Integer	The expiry month of the cryptogram. Formatted as N2 (e.g. 11).
expyear	Integer	The expiry year of the cryptogram. Formatted as N4 (e.g. 2099).
par	String	Payment account reference. Used for digital receipts and loyalty.
paymentdataid	String	The unique reference to the cryptogram stored at Cardtokens.
scheme	String	The card scheme of the cryptogram. It can be of “visa”, “mastercard” or “testscheme”.
tokenid	String	The tokenid passed as request for creating the cryptogram.

Example request

{
  "reference": "123j12323",
  "transactiontype": "ecom",
  "unpredictablenumber": "87654321"
}

Example response

{
  "cryptogram": "NTk0ZjM5M2QyNDMwNDE1MjkzMjg1ZTg5Y2NiZjdmNjE=",
  "token": "4492697777715235",
  "expmonth": 2,
  "expyear": 2028,
  "par": "91e2eb3cc21347499aa2c74c218f4fc8",
  "paymentdataid": "7f62909ce76147a99525f5c699d17ef8",
  "scheme": "testscheme",
  "tokenid": "529d7cb6a75e4bab8d71eb09dcd489e0"
}

Cryptogram lifetime

When cryptograms are created, the cryptogram must be stored in memory only! It’s a requirement from the major schemes. That means a new cryptogram must be requested on runtime every time a CIT payment is made and immediately used in the authorization towards the acquirer.

The cryptogram cannot be reused if the authorization is declined. Cryptograms are generated for a specific transaction, and their purpose is to verify its authenticity. If a transaction is denied, the issuer or the payment processor has determined that the transaction is invalid or rejected for some reason. In such a case, a new cryptogram must be generated and used in a new authorization.

3D secure testing

Unfortunately, there is no option to test the create cryptogram API call using a test-API-key. Instead, live production tests must be performed to test the full end-2-end flow using a secure server. Please get in touch with Cardtokens for information on how to perform this test.

Get cryptogram for CIT / MIT

Normally it’s only for CIT type of payment flows where a cryptogram is required. For MIT the cryptogram is only required for the first authorization / sign-up. For the subsequent authorizations, the payment service provider normally refers to the previous or initial authorization where the cryptogram was requested.