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...",    "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"}

Card-Specific Requirements

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

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

Country-Specific Requirements

These fields are required for transactions in specific countries.

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

Required Fields for Setup with a TMS Token

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

Field	Notes
`paymentInformation.card.expirationMonth`
`paymentInformation.card.expirationYear`
`paymentInformation.customer.customerId`

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"}

{  "orderInformation": { "..." },  "paymentInformation": { "..." },  "deviceInformation": { "..." },  "consumerAuthenticationInformation": {    "deviceChannel": "Browser",    "referenceId": "CybsCruiseTester-6259e7e2"  }}

{  "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"}

Card-Specific Requirements

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

Field	Requirement
`consumerAuthenticationInformation.defaultCard`	Recommended for Discover ProtectBuy.
`consumerAuthenticationInformation.mcc`	Required when the card type is Cartes Bancaires.
`consumerAuthenticationInformation.productCode`	Required for American Express SafeKey (US) when the product code is `AIR` for an airline purchase.
`merchantInformation.merchantDescriptor.name`	Required for Visa Secure travel.
`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).
`paymentInformation.card.type`	Required when the card type is Cartes Bancaires, JCB, China UnionPay, or Meeza.

Country-Specific Requirements

Field	Requirement
`consumerAuthenticationInformation.merchantScore`	Required for transactions processed in France.
`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.
`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`.

Required Fields for Checking Enrollment with a TMS Token

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.

Field	Notes
`consumerAuthenticationInformation.deviceChannel`
`consumerAuthenticationInformation.referenceId`
`paymentInformation.customer.customerId`
`deviceInformation.httpAcceptBrowserValue`
`deviceInformation.httpAcceptContent`
`deviceInformation.httpBrowserColorDepth`
`deviceInformation.httpBrowserJavaEnabled`
`deviceInformation.httpBrowserJavaScriptEnabled`
`deviceInformation.httpBrowserLanguage`
`deviceInformation.httpBrowserScreenHeight`
`deviceInformation.httpBrowserScreenWidth`
`deviceInformation.httpBrowserTimeDifference`
`deviceInformation.ipAddress`
`deviceInformation.userAgentBrowserValue`	When the customer's browser provides this value, you must include it in your request.
`orderInformation.amountDetails.currency`
`orderInformation.amountDetails.totalAmount`	Required when the `orderInformation.lineItems.unitPrice` field is not used.
`orderInformation.billTo.address1`
`orderInformation.billTo.address2`
`orderInformation.billTo.administrativeArea`	Required for the US and Canada.
`orderInformation.billTo.country`	Required for the US and Canada.
`orderInformation.billTo.email`
`orderInformation.billTo.firstName`
`orderInformation.billTo.lastName`
`orderInformation.billTo.locality`
`orderInformation.billTo.phoneNumber`
`orderInformation.billTo.postalCode`
`paymentInformation.card.expirationYear`
`paymentInformation.card.expirationMonth`
`paymentInformation.card.type`

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"}

Card-Specific Requirements

Field	Requirement
`consumerAuthenticationInformation.defaultCard`	Recommended for Discover ProtectBuy.
`consumerAuthenticationInformation.mcc`	Required when the card type is Cartes Bancaires.
`consumerAuthenticationInformation.productCode`	Required for American Express SafeKey (US) when the product code is `AIR` for an airline purchase.
`merchantInformation.merchantDescriptor.name`	Required for Visa Secure travel.
`orderInformation.shipTo.address1`	Required only for American Express SafeKey (US).
`orderInformation.shipTo.address2`	Required only for American Express SafeKey (US).

Country-Specific Requirements

Field	Requirement
`consumerAuthenticationInformation.merchantScore`	Required for transactions processed in France.
`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`.

Required Fields for Validating a Challenge with a TMS Token

Field	Notes
`consumerAuthenticationInformation.authenticationTransactionId`

Was this page helpful?

Last published: September 29, 2026