TMS Token Use Cases

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

Setting Up Device Data Collection with a TMS Token

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 scenario, a TMS token is used instead of the card.

Endpoint

POST /risk/v1/authentication-setups

Example: Setup with a TMS Token

{  "paymentInformation": {    "card": {      "expirationMonth": "05",      "expirationYear": "2029"    },    "customer": {      "customerId": "1108590036500854"    }  }}

{  "consumerAuthenticationInformation": {    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiIxZmQ5ZWIyNi1jOTY1LTRkZmEtYTM5Yy1hZDExMGU2NjQ3ZmMiLCJpYXQiOjE3MjUzNDcwNDksImlzcyI6IjVkZDgzYmYwMGU0MjNkMTQ5OGRjYmFjYSIsImV4cCI6MTcyNTM1MDY0OSwiT3JnVW5pdElkIjoiNjY0MWRiMGZmOTRmNzI3ZjU0Y2RlOTQ2IiwiUmVmZXJlbmNlSWQiOiIzZGM2ZDhmZS1lM2I1LTQyMTItYWY5MC1jNDcxYjczMTYwMjAifQ.90_yhusiQL9Yq10221zB04vZAKaiGnQ2ryvakeyuk1k",    "deviceDataCollectionUrl": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",    "referenceId": "3dc6d8fe-e3b5-4212-af90-c471b7316020",    "token": "AxizbwSTiTYf1D7m/jQkAG8BT34jOu4gAhLwyaSZejF9z2oA8AAA0gbV"  },  "id": "7253470490136808404004",  "status": "COMPLETED",  "submitTimeUtc": "2024-09-03T07:04:09Z"}

These fields are the minimum fields required when you request the Payer Authentication Setup service.

Required Fields for Setup with a TMS Token

paymentInformation.card.expirationMonth string

paymentInformation.card.expirationYear string

paymentInformation.customer.customerId string

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

Card-Specific Fields for Setup with a TMS Token

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 Setup with a TMS Token

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` if Egypt was not set as the country in merchant configuration during merchant boarding.
`merchantInformation.merchantDescriptor.country`	For Meeza transactions, this value must be set to `EG` if Egypt was 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 When Using a TMS Token

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 use case demonstrates this process while using a TMS token.

Endpoint

POST /risk/v1/authentications

Example: Check Enrollment with a TMS Token

{  "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": {    "card": {      "expirationMonth": "05",      "expirationYear": "2029"    },    "customer": {      "customerId": "1108590036500854"    }  },  "deviceInformation": {    "httpAcceptBrowserValue": "data",    "httpAcceptContent": "pa_http_user_accept_value",    "httpBrowserLanguage": "en_us",    "httpBrowserJavaEnabled": false,    "httpBrowserJavaScriptEnabled": false,    "httpBrowserColorDepth": "24",    "httpBrowserScreenHeight": "864",    "httpBrowserScreenWidth": "1536",    "httpBrowserTimeDifference": "300",    "userAgentBrowserValue": "123"  },  "consumerAuthenticationInformation": {    "deviceChannel": "Browser",    "referenceId": "CybsCruiseTester-6259e7e2"  }}

{  "consumerAuthenticationInformation": {    "eciRaw": "05",    "authenticationTransactionId": "e2elnNP8zJ2J67lKcaX0",    "strongAuthentication": {      "OutageExemptionIndicator": "0"    },    "eci": "05",    "token": "AxjzbwSTiTYllZBAC15FAG8BT34jOzxHSBcS0JeGTSTL0Yvue1AHgAAAyxUk",    "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",    "paresStatus": "Y",    "acsReferenceNumber": "Cardinal ACS",    "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",    "directoryServerTransactionId": "3859eace-2a42-4bd7-9252-8507f02d5edd",    "veresEnrolled": "Y",    "threeDSServerTransactionId": "932a3c41-880d-4791-a98f-c6beaef90b23",    "acsOperatorID": "MerchantACS",    "ecommerceIndicator": "vbv",    "specificationVersion": "2.1.0",    "acsTransactionId": "54ef7fd4-e93d-42de-82ba-ad91dd21c94c"  },  "id": "7253472110066822504005",  "paymentInformation": {    "card": {      "bin": "400009",      "type": "VISA"    }  },  "status": "AUTHENTICATION_SUCCESSFUL",  "submitTimeUtc": "2024-09-03T07:06:51Z"}

{  "consumerAuthenticationInformation": {    "challengeRequired": "N",    "authenticationTransactionId": "z7BruZ1qn416WGknmAX0",    "strongAuthentication": {      "OutageExemptionIndicator": "0"    },    "token": "AxjzbwSTiTcMOwhjPANlAG8BT34jQMsnSBcS0JddrSTL0Yvue1AIAAAA+AWf",    "acsUrl": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",    "acsReferenceNumber": "Cardinal ACS",    "stepUpUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",    "pareq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEi...",    "directoryServerTransactionId": "2f44602b-ce95-4a7e-9ad1-920e7ace0676",    "veresEnrolled": "Y",    "threeDSServerTransactionId": "4e50f586-b15c-4c03-a186-eafb40d50b80",    "acsOperatorID": "MerchantACS",    "specificationVersion": "2.1.0",    "acsTransactionId": "3888e153-6b97-4f43-afee-60527c2e0b91"  },  "errorInformation": {    "reason": "CONSUMER_AUTHENTICATION_REQUIRED",    "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction."  },  "id": "7253537031246871004005",  "paymentInformation": {    "card": {      "bin": "400009",      "type": "VISA"    }  },  "status": "PENDING_AUTHENTICATION",  "submitTimeUtc": "2024-09-03T08:55:03Z"}

These fields are the minimum fields required for verifying that a customer is enrolled in a payer authentication program. The same fields are required whether the enrollment check is frictionless or results in a challenge.

Required Fields for Checking Enrollment with a TMS Token

consumerAuthenticationInformation.deviceChannel string

consumerAuthenticationInformation.referenceId string

paymentInformation.customer.customerId string

deviceInformation.httpAcceptBrowserValue string

deviceInformation.httpAcceptContent string

deviceInformation.httpBrowserColorDepth string

deviceInformation.httpBrowserJavaEnabled boolean

deviceInformation.httpBrowserJavaScriptEnabled boolean

deviceInformation.httpBrowserLanguage string

deviceInformation.httpBrowserScreenHeight string

deviceInformation.httpBrowserScreenWidth string

deviceInformation.httpBrowserTimeDifference string

deviceInformation.ipAddress string

deviceInformation.userAgentBrowserValue string

When the customer's browser provides this value, you must include it in your request.

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.card.expirationYear string

paymentInformation.card.expirationMonth string

paymentInformation.card.type string

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

Card-Specific Fields for Checking Enrollment with a TMS Token

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 Cartes Bancaires, JCB, China UnionPay, or Meeza.

China UnionPay 1 field

Field	Description
`paymentInformation.card.type`	Required when the card type is Cartes Bancaires, JCB, 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 Cartes Bancaires, JCB, China UnionPay, or Meeza.

Meeza 1 field

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

Visa Secure 1 field

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

Country-Specific Fields for Checking Enrollment with a TMS Token

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 merchant 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`.

Validating a Challenge When Using a TMS Token

Running the Validation service compares the customer's response to the challenge from the issuing bank to validate the customer identity.

Endpoint

POST /risk/v1/authentication-results

Example: Validate Challenge with a TMS Token

{  "clientReferenceInformation": {    "code": "pavalidatecheck",    "partner": {      "developerId": "7891234",      "solutionId": "89012345"    }  },  "consumerAuthenticationInformation": {    "authenticationTransactionId": "z7BruZ1qn416WGknmAX0"  }}

{  "clientReferenceInformation": {    "code": "pavalidatecheck",    "partner": {      "developerId": "7891234",      "solutionId": "89012345"    }  },  "consumerAuthenticationInformation": {    "indicator": "vbv",    "eciRaw": "05",    "authenticationResult": "0",    "strongAuthentication": {      "OutageExemptionIndicator": "0"    },    "authenticationStatusMsg": "Success",    "eci": "05",    "token": "AxijLwSTiTcQGTMcD52lAG9PfiNA2ogCEvDJpJl6MX3PagAAmh21",    "cavv": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",    "paresStatus": "Y",    "xid": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",    "directoryServerTransactionId": "2f44602b-ce95-4a7e-9ad1-920e7ace0676",    "threeDSServerTransactionId": "4e50f586-b15c-4c03-a186-eafb40d50b80",    "specificationVersion": "2.1.0",    "acsTransactionId": "3888e153-6b97-4f43-afee-60527c2e0b91"  },  "id": "7253538119946872004005",  "paymentInformation": {    "card": {      "bin": "400009",      "type": "VISA"    }  },  "status": "AUTHENTICATION_SUCCESSFUL",  "submitTimeUtc": "2024-09-03T08:56:52Z"}

Required Fields for Validating a Challenge with a TMS Token

consumerAuthenticationInformation.authenticationTransactionId string

Card-Specific Fields for Validating a Challenge with a TMS Token

American Express SafeKey (US) 3 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).

Cartes Bancaires 1 field

Field	Description
`consumerAuthenticationInformation.mcc`	Required when the card type is Cartes Bancaires.

Discover ProtectBuy 1 field

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

Visa Secure 1 field

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

Country-Specific Fields for Validating a Challenge with a TMS Token

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`.

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 TMS Token

Checking Enrollment When Using a TMS Token

Validating a Challenge When Using a TMS Token

Not available for your audience