Standard Use Cases

These examples list the REST API fields required or optional for the Setup, Check Enrollment, and Validate Authentication services. An example request payload and a successful response for each service are provided. Payer authentication has three types of examples:

Primary Account Number (PAN): Illustrates how the payer authentication services work with customer PANs during transactions.
Tokens: Illustrates how the payer authentication services work with different types of tokens.
3RI: Illustrates how the payer authentication services work with merchant-initiated transactions.

In certain circumstances, some payment card companies and some countries require more information than is normally collected when authenticating the customer. These circumstances, and the API fields to use in those circumstances, are noted for each case.

Device Data Collection Setup

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.

Example: Device Data Collection Setup

POST /risk/v1/authentication-setups

{  "paymentInformation": {    "card": {      "type": "001",      "expirationMonth": "12",      "expirationYear": "2025",      "number": "4XXXXXXXXXXXXXXX"    }  }}

{  "clientReferenceInformation": {    "code": "1675295420285"  },  "consumerAuthenticationInformation": {    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",    "deviceDataCollectionUrl": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",    "referenceId": "39160c2d-c1e4-4465-ace3-eb32d5a1d559",    "token": "AxizbwSTbhQQxCrDMCazABEBT9u+U5WYAXsQyaSZejFczCmAMAAAwAnp"  },  "id": "6752954202146024203955",  "status": "COMPLETED",  "submitTimeUtc": "2023-02-01T23:50:20Z"}

Required Fields for Device Data Collection

These fields are the minimum fields required when you request the Payer Authentication Setup service. Other fields that can be used to collect additional information during a transaction are listed in the optional fields section. Under certain circumstances, a field that is normally optional might be required.

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.
`orderInformation.billTo.administrativeArea`	This field is required for the US and Canada.
`orderInformation.billTo.postalCode`	This field is required when the `orderInformation.billTo.country` field value is `US` or `CA`.
`paymentInformation.card.expirationMonth`
`paymentInformation.card.expirationYear`
`paymentInformation.card.number`
`paymentInformation.card.type`	This field is required when the card type is Cartes Bancaires, JCB, China UnionPay, or Meeza.

Optional Fields for Device Data Collection

These fields are optional for setting up a Payer Authentication transaction.

Field	Description
`clientReferenceInformation.code`
`orderInformation.billTo.address1`
`orderInformation.billTo.administrativeArea`
`orderInformation.billTo.country`
`orderInformation.billTo.email`
`orderInformation.billTo.firstName`
`orderInformation.billTo.lastName`
`orderInformation.billTo.locality`
`orderInformation.billTo.postalCode`

Check Enrollment

The Check Enrollment service tries to authenticate the cardholder. If the cardholder can be authenticated without additional information, the transaction can be authorized. If more information is required, the cardholder is challenged to provide additional authentication.

POST /risk/v1/authentications

Example: Check Enrollment

{    "orderInformation": {        "amountDetails": {            "currency": "USD",            "totalAmount": "100"        },        "billTo": {            "address1": "901 metro center blvd",            "address2": "metro 3",            "administrativeArea": "CA",            "country": "US",            "locality": "san francisco",            "firstName": "John",            "lastName": "Doe",            "phoneNumber": "18007097779",            "postalCode": "94404",            "email": "[email protected]"        }    },    "paymentInformation": {        "card": {            "number": "4XXXXXXXXXXXXXXX",            "expirationMonth": "08",            "expirationYear": "2026"        }    },    "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": {        "referenceId": "c44224db-0dda-40aa-9536-ac1595fd2e8d",        "transactionMode": "S",        "returnUrl": "https://wv730hw7033250:3002/restapi/cardinalDirect/StepUp/Response"    }}

{    "clientReferenceInformation": {      "code": "1675295420285"    },    "consumerAuthenticationInformation": {        "acsUrl": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",        "challengeRequired": "N",        "stepUpUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",        "authenticationTransactionId": "1xRSpLPEoTNsinp8XUK0",        "pareq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEi...",        "directoryServerTransactionId": "4d19781a-49d7-4c90-a145-72b8107fed8f",        "veresEnrolled": "Y",        "threeDSServerTransactionId": "84e6c23b-e621-464e-aaec-18cdd15a0eec",        "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",        "specificationVersion": "2.1.0",        "token": "AxjzbwSTVZPTJPD7ixR8ADUBURxP1CnnpA6cQE1129JMvRiuHCKArAAAx/+g",        "acsTransactionId": "ee745e3c-c267-4c34-9311-0b7560c2d68f"    },    "errorInformation": {        "reason": "CONSUMER_AUTHENTICATION_REQUIRED",        "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction."    },    "id": "6300991627296049403004",    "paymentInformation": {        "card": {            "bin": "4XXXXXXX",            "type": "VISA"        }    },    "status": "PENDING_AUTHENTICATION",    "submitTimeUtc": "2022-08-27T21:19:23Z"}

Card-Specific Requirements

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

Field	Description
`consumerAuthenticationInformation.defaultCard`	This field is recommended for Discover ProtectBuy.
`consumerAuthenticationInformation.mcc`	This field is required when the card type is Cartes Bancaires.
`consumerAuthenticationInformation.productCode`	This field is required for American Express SafeKey (U.S.) when the product code is `AIR` for an airline purchase.
`merchantInformation.merchantDescriptor.name`	This field is required for Visa Secure travel.
`orderInformation.shipTo.address1`	This field is required only for American Express SafeKey (US).
`orderInformation.shipTo.address2`	This field is required only for American Express SafeKey (US).
`orderInformation.shipTo.administrativeArea`	This field is required only for American Express SafeKey (US).
`orderInformation.shipTo.country`	This field is required for American Express SafeKey (US).
`orderInformation.shipTo.postalCode`	This field is required for American Express SafeKey (US).
`paymentInformation.card.type`	This field is 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	Description
`consumerAuthenticationInformation.merchantScore`	This field is 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`	This field is required for transactions in the US and Canada.
`orderInformation.billTo.locality`	This field is required for transactions in the US and Canada.
`orderInformation.billTo.postalCode`	This field is required when the `orderInformation.billTo.country` field value is `US` or `CA`.
`orderInformation.shipTo.administrativeArea`	This field is required when the `orderInformation.shipTo.country` field value is `CA`, `US`, or `China`.
`orderInformation.shipTo.postalCode`	This field is required when the `orderInformation.shipTo.country` field value is `US` or `CA`.

Processor-Specific Requirements

These fields are required by specific processors for transactions.

Field	Description
`processingInformation.authorizationOptions.transactionMode`	This field is required only for merchants in Saudi Arabia.

Required Fields for Check Enrollment

These fields are the minimum fields required for verifying that a customer is enrolled in a payer authentication program.

Field	Description
`buyerInformation.mobilePhone`	This field is required (when available) if `buyerInformation.workPhone` is not used, unless market or regional mandate restricts sending this information.
`buyerInformation.workPhone`	This field is required (when available) if `buyerInformation.mobilePhone` is not used, unless market or regional mandate restricts sending this information.
`consumerAuthenticationInformation.deviceChannel`	This field is required for SDK integration. When you use the SDK integration, this field is dynamically set to `SDK`. When you use the JavaScript code, this field is dynamically set to `Browser`. For merchant-initiated or 3RI transactions, you must set the field to 3RI.
`consumerAuthenticationInformation.messageCategory`	For non-payment authentication, set to a value of `02`.
`consumerAuthenticationInformation.referenceId`
`consumerAuthenticationInformation.returnUrl`
`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.
`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 that value in your request.
`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.amountDetails.currency`
`orderInformation.amountDetails.totalAmount`	This field is required when the `orderInformation.lineItems.unitPrice` field is not used.
`orderInformation.billTo.address1`
`orderInformation.billTo.administrativeArea`	This field is required for transactions in the US and Canada.
`paymentInformation.card.expirationYear`	This field is required when the `paymentInformation.card.number` field is included.
`paymentInformation.card.expirationMonth`	This field is required when the `paymentInformation.card.number` field is included.
`paymentInformation.card.type`
`paymentInformation.card.number`

Checking Enrollment and Authorizing a Transaction

The Check Enrollment service can be combined with the Authorization service so that when a customer's authentication does not require a challenge, the transaction is automatically submitted for authorization.

POST /risk/v1/authentications

Example: Check Enrollment and Authorization

{    "clientReferenceInformation": {        "code": "test"    },    "processingInformation": {        "capture": "true",        "actionList": [            "CONSUMER_AUTHENTICATION"        ]    },    "paymentInformation": {        "card": {            "expirationYear": "2031",            "number": "4XXXXXXXXXXX2701",            "securityCode": "123",            "expirationMonth": "12",            "type": "001"        }    },    "orderInformation": {        "amountDetails": {            "totalAmount": "100.00",            "currency": "GBP"        },        "billTo": {            "firstName": "John",            "lastName": "Smith",            "address1": "201 S. Division St._1",            "address2": "Suite 500",            "locality": "Foster City",            "administrativeArea": "CA",            "postalCode": "94404",            "country": "US",            "email": "[email protected]",            "phoneNumber": "6504327113"        }    },    "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": {        "returnUrl": "https://webhook.site/bdf16530-2577-4885-9dee-e9d6c4f98bc0",        "referenceId": "72b727bc-a6a4-4481-b25c-a5939d48fef6"    }}

{    "clientReferenceInformation": {        "code": "test"    },    "consumerAuthenticationInformation": {        "eciRaw": "05",        "authenticationTransactionId": "2BE13ZGIzjXdFfKw2Fi0",        "eci": "05",        "token": "Axj//wSTlWVuE5k5bxqFAAIU3YMmzhgzYM2Ce/LXc7XAKe/LXc7XZ0OnEFBWGTSTL0Yua1eAwHScqytwnMnLeNQo+xnO",        "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",        "paresStatus": "Y",        "directoryServerTransactionId": "4689476f-168b-415e-bad5-aee47a270086",        "veresEnrolled": "Y",        "threeDSServerTransactionId": "bda6f2d1-5c18-4589-a150-1e8c6e795e85",        "specificationVersion": "2.2.0",        "acsTransactionId": "5bbd605d-80e4-48ef-82b5-0406774c66e3"    },    "id": "7478240150646451804805",    "orderInformation": {        "amountDetails": {            "totalAmount": "100.00",            "authorizedAmount": "100.00",            "currency": "GBP"        }    },    "status": "AUTHORIZED",    "submitTimeUtc": "2025-05-21T10:40:15Z"}

Card-Specific Requirements

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

Field	Description
`consumerAuthenticationInformation.defaultCard`	This field is recommended for Discover ProtectBuy.
`consumerAuthenticationInformation.mcc`	This field is required when the card type is Cartes Bancaires.
`consumerAuthenticationInformation.productCode`	This field is required for American Express SafeKey (U.S.) when the product code is `AIR` for an airline purchase.
`merchantInformation.merchantDescriptor.name`	This field is required for Visa Secure travel.
`orderInformation.shipTo.address1`	This field is required only for American Express SafeKey (US).
`orderInformation.shipTo.address2`	This field is required only for American Express SafeKey (US).
`orderInformation.shipTo.administrativeArea`	This field is required only for American Express SafeKey (US).
`orderInformation.shipTo.country`	This field is required for American Express SafeKey (US).
`orderInformation.shipTo.postalCode`	This field is required for American Express SafeKey (US).
`paymentInformation.card.type`	This field is required when the card type is JCB, Cartes Bancaires, China UnionPay, or Meeza.

Validating a Challenge

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

POST /risk/v1/authentication-results

Example: Validate a Challenge

{  "paymentInformation": {    "card": {      "type": "001"    }  },  "consumerAuthenticationInformation": {    "authenticationTransactionId": "bE4fdH96vKejWyz6rXy1"  }}

{  "consumerAuthenticationInformation": {    "indicator": "vbv",    "eciRaw": "05",    "authenticationResult": "0",    "authenticationStatusMsg": "Success",    "eci": "05",    "token": "AxijLwSTVYSa8ZmiITBhAAJRHE+rXi4ATWhk0kyxdfAuewAA4iW6",    "cavv": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",    "paresStatus": "Y",    "xid": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",    "directoryServerTransactionId": "144ecc30-264f-4d2c-8a4e-798a4f311b1f",    "threeDSServerTransactionId": "6773483d-e16a-40f5-bc5d-93d709c8a06b",    "specificationVersion": "2.1.0",    "acsTransactionId": "6eab6816-72d2-40e8-a03f-0a6c8bfe3156"  },  "id": "6299894944336529404001",  "paymentInformation": {    "card": {      "bin": "400000",      "type": "VISA"    }  },  "status": "AUTHENTICATION_SUCCESSFUL",  "submitTimeUtc": "2021-08-26T14:51:34Z"}

Card-Specific Requirements

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

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

Country-Specific Requirements

These fields are required for transactions in specific countries.

Field	Description
`consumerAuthenticationInformation.merchantScore`	This field is required for transactions processed in France.
`orderInformation.billTo.administrativeArea`	This field is required for transactions in the US and Canada.
`orderInformation.billTo.locality`	This field is required for transactions in the US and Canada.
`orderInformation.billTo.postalCode`	This field is required when the `orderInformation.billTo.country` field value is `US` or `CA`.

Required Fields for Validating a Challenge

These are the minimum fields required when validating the customer.

Field	Description
`consumerAuthenticationInformation.authenticationTransactionId`
`paymentInformation.card.type`

Validating and Authorizing a Transaction

The Validation service can be combined with the Authorization service so that when a customer's authentication is validated, the service automatically submits the transaction for authorization.

POST /pts/v2/payments

See the Payments API reference for the required authorization fields and request/response examples when combining payer authentication validation with authorization (POST /pts/v2/payments).

Fields Specific to a Visa Secure Transaction

These API fields are required specifically for this use case.

Field	Description
`processingInformation.commerceIndicator`	Set this field to `vbv` for a successful authentication (EMV 3-D Secure value of `05`), `vbv_attempted` if authentication was attempted but did not succeed (EMV 3-D Secure value of `06`), or `vbv_failure` if authentication failed (EMV 3-D Secure value of `07`).
`consumerAuthenticationInformation.cavv`	This field is required when payer authentication is successful.

Card-Specific Requirements

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

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

Country-Specific Requirements

These fields are required for transactions in specific countries.

Field	Description
`consumerAuthenticationInformation.merchantScore`	This field is required for transactions processed in France.
`orderInformation.billTo.locality`	This field is required for transactions in the US and Canada.
`orderInformation.billTo.postalCode`	This field is required when the `orderInformation.billTo.country` field value is `US` or `CA`.
`orderInformation.billTo.administrativeArea`	This field is required for transactions in the US and Canada.

Non-Payment Authentication

Non-Payment Authentication (NPA) requests enable a merchant to authenticate a customer without a transaction. A non-payment use case can be used for tasks such as adding a card to a merchant website, updating cardholder information on file, or to verify a cardholder's identity when creating a token for future use. The same authentication used during the checking enrollment process is used for NPA. Non-payment use cases are enabled using a combination of the consumerAuthenticationInformation.messageCategory and consumerAuthenticationInformation.strongAuthentication.authenticationIndicator values. For example, to add a card to a loyalty program, set the Message Category value to 02 and the Authentication Indicator value to 04. The consumerAuthenticationInformation.messageCategory value must be set to 02 (non-payment authentication) to specify that the authentication is not for a transaction.

POST /risk/v1/authentications

Example: Non-Payment Authentication Check Enrollment

{  "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": {      "type": "001",      "expirationMonth": "12",      "expirationYear": "2025",      "number": "4XXXXXXXXXXX2503"    }  },  "buyerInformation": {    "merchantCustomerId": "334124572",    "mobilePhone": "1245789632"  },  "deviceInformation": {    "ipAddress": "139.130.4.5",    "httpAcceptContent": "test",    "httpBrowserLanguage": "en_us",    "httpBrowserJavaEnabled": false,    "httpBrowserJavaScriptEnabled": false,    "httpBrowserColorDepth": "24",    "httpBrowserScreenHeight": "100000",    "httpBrowserScreenWidth": "100000",    "httpBrowserTimeDifference": "300",    "userAgentBrowserValue": "GxKnLy8TFDUFxJP1t"  },  "consumerAuthenticationInformation": {    "deviceChannel": "BROWSER",    "messageCategory": "02",    "transactionMode": "eCommerce"  }}

{  "clientReferenceInformation": {    "code": "1729234929433"  },  "consumerAuthenticationInformation": {    "challengeRequired": "N",    "authenticationTransactionId": "MXvfrk1911nHJpC18OI0",    "token": "AxjzbwSTi1GtFWKe0Yg5ABEBTyDdd93DSBcS0MRdrSTL0YrmYUwDgAAAWBV8",    "acsUrl": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",    "stepUpUrl": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",    "pareq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEi...",    "directoryServerTransactionId": "0656bace-7519-4dd9-9450-98dfc6f35d7c"  },  "status": "PENDING_AUTHENTICATION",  "submitTimeUtc": "2024-10-18T09:42:09Z"}

Card-Specific Requirements

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

Field	Description
`consumerAuthenticationInformation.defaultCard`	This field is recommended for Discover ProtectBuy.
`consumerAuthenticationInformation.mcc`	This field is required when the card type is Cartes Bancaires.
`consumerAuthenticationInformation.productCode`	This field is required for American Express SafeKey (U.S.) when the product code is `AIR` for an airline purchase.
`merchantInformation.merchantDescriptor.name`	This field is required for Visa Secure travel.
`orderInformation.shipTo.address1`	This field is required only for American Express SafeKey (US).
`orderInformation.shipTo.address2`	This field is required only for American Express SafeKey (US).
`orderInformation.shipTo.administrativeArea`	This field is required only for American Express SafeKey (US).
`orderInformation.shipTo.country`	This field is required only for American Express SafeKey (US).
`orderInformation.shipTo.postalCode`	This field is required for American Express SafeKey (US).
`paymentInformation.card.type`	This field is 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	Description
`consumerAuthenticationInformation.merchantScore`	This field is 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`	This field is required for transactions in the US and Canada.
`orderInformation.billTo.locality`	This field is required for transactions in the US and Canada.
`orderInformation.billTo.postalCode`	This field is required when the `orderInformation.billTo.country` field value is `US` or `CA`.

Was this page helpful?

Last published: September 29, 2026