Tokenized Card Use Cases

These examples list the API fields required for the Setup, Check Enrollment, and Validate Authentication services when using network tokens or tokenized cards. An example of a request payload and a successful response for each service is provided.

Setting Up Device Data Collection with a Network Token/Tokenized Card

Running the Setup service identifies the customer's bank and prepares for collecting data about the device that the customer is using to place the order. In this instance, a tokenized card is used instead of the payment card data.

Endpoint

POST /risk/v1/authentication-setups

Example: Setup with a Network Token/Tokenized Card

{  "paymentInformation": {    "tokenizedCard": {      "transactionType": "1",      "type": "001",      "expirationMonth": "11",      "expirationYear": "2025",      "number": "4111111111111111"    }  }}

{  "clientReferenceInformation": {    "code": "1725450205426"  },  "consumerAuthenticationInformation": {    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiJlOGI4ODk5Ny1iYzY2LTRkYTEtOTYyNi1iNTc3MTlhNTczNzAiLCJpYXQiOjE3MjU0NTAyMDUsImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTcyNTQ1Mzg54TV09PladElkIjoiNWI5YzRiYjNmZjYyNmIxMzQ0ODEwYTAxIiwiUmVmZXJlbmNlSWQiOiJiYmY4YzU3NS01NjRiLTQzYWYtOGI1Yy0yODdiNmU2ZWM4OGYifQ.UVNLUVmFJKwFxIO1prb5hpaKRR5WRI3esl0UnRg37Fg",    "deviceDataCollectionUrl": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",    "referenceId": "bbf8c575-564b-43af-8b5c-287b6e6ec88f",    "token": "AxizbwSTiURwrn44LBakABEBTyDYGB7gAhMQyaSZejFczCmAmAAAzghh"  },  "id": "7254502054416956004004",  "status": "COMPLETED",  "submitTimeUtc": "2024-09-04T11:43:25Z"}

These fields are the minimum fields required when you request the Payer Authentication Setup service while using a tokenized card. Other required Setup service fields are listed in the Required Fields for Collecting Device Data topic.

Required Fields for Setup with a Network Token/Tokenized Card

paymentInformation.tokenizedCard.expirationMonth string

paymentInformation.tokenizedCard.expirationYear string

paymentInformation.tokenizedCard.number string

paymentInformation.tokenizedCard.transactionType string

paymentInformation.tokenizedCard.type string

Some payment cards require additional information to be collected during a transaction.

Card-Specific Fields for Setting Up Device Data Collection with a Network Token/Tokenized Card

Cartes Bancaires 1 field

Field	Description
`paymentInformation.card.type`	Required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

China UnionPay 1 field

Field	Description
`paymentInformation.card.type`	Required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

JCB 1 field

Field	Description
`paymentInformation.card.type`	Required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

Meeza 1 field

Field	Description
`paymentInformation.card.type`	Required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

These fields are required for transactions in specific countries.

Country-Specific Fields for Setting Up Device Data Collection with a Network Token/Tokenized Card

Canada 2 fields

Field	Description
`orderInformation.billTo.administrativeArea`	Required for transactions in the US and Canada.
`orderInformation.billTo.postalCode`	Required when the `orderInformation.billTo.country` field value is `US` or `CA`.

Egypt (Meeza transactions) 2 fields

Field	Description
`consumerAuthenticationInformation.overrideCountryCode`	For Meeza transactions, this value must be set to `EG` when Egypt is not set as the country in merchant configuration during merchant boarding.
`merchantInformation.merchantDescriptor.country`	For Meeza transactions, this value must be set to `EG` when Egypt is not set as the country in merchant configuration during merchant boarding.

United States 2 fields

Field	Description
`orderInformation.billTo.administrativeArea`	Required for transactions in the US and Canada.
`orderInformation.billTo.postalCode`	Required when the `orderInformation.billTo.country` field value is `US` or `CA`.

Checking Enrollment with a Network Token/Tokenized Card

The Check Enrollment service identifies the customer's bank and collects data about the device that the customer is using to place the order. This instance demonstrates this process with a network token/tokenized card.

Endpoint

POST /risk/v1/authentications

Example: Check Enrollment with a Network Token/Tokenized Card (Frictionless)

{  "orderInformation": {    "amountDetails": {      "currency": "USD",      "totalAmount": "10.99"    },    "billTo": {      "address1": "1 Market St",      "address2": "Address 2",      "administrativeArea": "CA",      "country": "US",      "locality": "san francisco",      "firstName": "John",      "lastName": "Doe",      "phoneNumber": "4158880000",      "email": "[email protected]",      "postalCode": "94105"    }  },  "paymentInformation": {    "tokenizedCard": {      "transactionType": "1",      "type": "001",      "expirationMonth": "11",      "expirationYear": "2025",      "number": "4111111111111111"    }  },  "deviceInformation": {    "ipAddress": "139.130.4.5",    "httpAcceptContent": "test",    "httpBrowserLanguage": "en_us",    "httpBrowserJavaEnabled": "N",    "httpBrowserJavaScriptEnabled": "Y",    "httpBrowserColorDepth": "24",    "httpBrowserScreenHeight": "100000",    "httpBrowserScreenWidth": "100000",    "httpBrowserTimeDifference": "300",    "userAgentBrowserValue": "GxKnLy8TFDUFxJP1t"  },  "consumerAuthenticationInformation": {    "deviceChannel": "BROWSER",    "referenceId": "CybsCruiseTester-a8a8eeaf"  }}

{  "clientReferenceInformation": {    "code": "1725450267324"  },  "consumerAuthenticationInformation": {    "eciRaw": "05",    "authenticationTransactionId": "o9spMK5vH7MK5lAPku60",    "strongAuthentication": {      "OutageExemptionIndicator": "0"    },    "eci": "05",    "token": "AxjzbwSTiURy4Xhjhs+lABEBTyDYGCNvSBcS0JiGTSTL0YrmYUwEwAAASAVA",    "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",    "paresStatus": "Y",    "acsReferenceNumber": "Cardinal ACS",    "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",    "directoryServerTransactionId": "51a3b89b-10c4-4718-8300-4cdc779d1434",    "veresEnrolled": "Y",    "threeDSServerTransactionId": "1a9c8944-6d0b-46d4-a964-5e986cff9c1b",    "acsOperatorID": "MerchantACS",    "ecommerceIndicator": "vbv",    "specificationVersion": "2.1.0",    "acsTransactionId": "b022828d-7440-4815-a5f8-28cf3f568f02"  },  "id": "7254502673416960004005",  "paymentInformation": {    "card": {      "bin": "411111",      "type": "VISA"    }  },  "status": "AUTHENTICATION_SUCCESSFUL",  "submitTimeUtc": "2024-09-04T11:44:27Z"}

Required Fields for Checking Enrollment with a Network Token/Tokenized Card

consumerAuthenticationInformation.deviceChannel string

consumerAuthenticationInformation.referenceId string

paymentInformation.customer.customerId string

orderInformation.amountDetails.currency string

orderInformation.amountDetails.totalAmount string

Required when the orderInformation.lineItems.unitPrice field is not used.

orderInformation.billTo.address1 string

orderInformation.billTo.address2 string

orderInformation.billTo.administrativeArea string

Required for the US and Canada.

orderInformation.billTo.country string

Required for the US and Canada.

orderInformation.billTo.email string

orderInformation.billTo.firstName string

orderInformation.billTo.lastName string

orderInformation.billTo.locality string

orderInformation.billTo.phoneNumber string

orderInformation.billTo.postalCode string

paymentInformation.tokenizedCard.expirationMonth string

paymentInformation.tokenizedCard.expirationYear string

paymentInformation.tokenizedCard.number string

paymentInformation.tokenizedCard.transactionType string

paymentInformation.tokenizedCard.type string

Some payment cards require information to be collected during a transaction.

Card-Specific Fields for Checking Enrollment with a Network Token/Tokenized Card

American Express SafeKey (US) 6 fields

Field	Description
`consumerAuthenticationInformation.productCode`	Required for American Express SafeKey (US) when the product code is `AIR` for an airline purchase.
`orderInformation.shipTo.address1`	Required only for American Express SafeKey (US).
`orderInformation.shipTo.address2`	Required only for American Express SafeKey (US).
`orderInformation.shipTo.administrativeArea`	Required only for American Express SafeKey (US).
`orderInformation.shipTo.country`	Required only for American Express SafeKey (US).
`orderInformation.shipTo.postalCode`	Required for American Express SafeKey (US).

Cartes Bancaires 2 fields

Field	Description
`consumerAuthenticationInformation.mcc`	Required when the card type is Cartes Bancaires.
`paymentInformation.card.type`	Required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

China UnionPay 1 field

Field	Description
`paymentInformation.card.type`	Required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

Discover ProtectBuy 1 field

Field	Description
`consumerAuthenticationInformation.defaultCard`	Recommended for Discover ProtectBuy.

JCB 1 field

Field	Description
`paymentInformation.card.type`	Required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

Meeza 1 field

Field	Description
`paymentInformation.card.type`	Required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

Visa Secure 1 field

Field	Description
`merchantInformation.merchantDescriptor.name`	Required for Visa Secure travel.

These fields are required for transactions in specific countries.

Country-Specific Fields for Checking Enrollment with a Network Token/Tokenized Card

Canada 3 fields

Field	Description
`orderInformation.billTo.administrativeArea`	Required for transactions in the US and Canada.
`orderInformation.billTo.locality`	Required for transactions in the US and Canada.
`orderInformation.billTo.postalCode`	Required when the `orderInformation.billTo.country` field value is `US` or `CA`.

Egypt (Meeza transactions) 2 fields

Field	Description
`consumerAuthenticationInformation.overrideCountryCode`	For Meeza transactions, this value must be set to `EG` when Egypt is not set as the country in the merchant configuration during boarding.
`merchantInformation.merchantDescriptor.country`	For Meeza transactions, this value must be set to `EG` when Egypt is not set as the country in the merchant configuration during merchant boarding.

France 1 field

Field	Description
`consumerAuthenticationInformation.merchantScore`	Required for transactions processed in France.

United States 3 fields

Field	Description
`orderInformation.billTo.administrativeArea`	Required for transactions in the US and Canada.
`orderInformation.billTo.locality`	Required for transactions in the US and Canada.
`orderInformation.billTo.postalCode`	Required when the `orderInformation.billTo.country` field value is `US` or `CA`.

Was this page helpful?

Last published: October 28, 2026

Setting Up Device Data Collection with a Network Token/Tokenized Card

Checking Enrollment with a Network Token/Tokenized Card

Not available for your audience