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": "2029",      "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"}

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.

Required Fields for Device Data Collection

consumerAuthenticationInformation.overrideCountryCode string

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 string

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 string

This field is required for the US and Canada.

orderInformation.billTo.postalCode string

This field is required when the orderInformation.billTo.country field value is US or CA.

paymentInformation.card.expirationMonth string

paymentInformation.card.expirationYear string

paymentInformation.card.number string

paymentInformation.card.type string

This field is required when the card type is Cartes Bancaires, JCB, China UnionPay, or Meeza.

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

Optional Fields for Device Data Collection

clientReferenceInformation.code string

orderInformation.billTo.address1 string

orderInformation.billTo.administrativeArea string

orderInformation.billTo.country string

orderInformation.billTo.email string

orderInformation.billTo.firstName string

orderInformation.billTo.lastName string

orderInformation.billTo.locality string

orderInformation.billTo.postalCode string

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": "2029"        }    },    "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://merchant.example.com/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"}

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

Required Fields for Check Enrollment

buyerInformation.mobilePhone string

This field is required (when available) if buyerInformation.workPhone is not used, unless market or regional mandate restricts sending this information.

buyerInformation.workPhone string

This field is required (when available) if buyerInformation.mobilePhone is not used, unless market or regional mandate restricts sending this information.

consumerAuthenticationInformation.deviceChannel string

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 string

For non-payment authentication, set to a value of 02.

consumerAuthenticationInformation.referenceId string

consumerAuthenticationInformation.returnUrl string

consumerAuthenticationInformation.overrideCountryCode string

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 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 that value in your request.

merchantInformation.merchantDescriptor.country string

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 string

orderInformation.amountDetails.totalAmount string

This field is required when the orderInformation.lineItems.unitPrice field is not used.

orderInformation.billTo.address1 string

orderInformation.billTo.administrativeArea string

This field is required for transactions in the US and Canada.

paymentInformation.card.expirationYear string

This field is required when the paymentInformation.card.number field is included.

paymentInformation.card.expirationMonth string

This field is required when the paymentInformation.card.number field is included.

paymentInformation.card.type string

paymentInformation.card.number string

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

Card-Specific Fields for Check Enrollment

American Express SafeKey (US) 6 fields

Field	Description
`consumerAuthenticationInformation.productCode`	This field is required for American Express SafeKey (U.S.) when the product code is `AIR` for an airline purchase.
`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).

Cartes Bancaires 2 fields

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

China UnionPay 1 field

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

Discover ProtectBuy 1 field

Field	Description
`consumerAuthenticationInformation.defaultCard`	This field is recommended for Discover ProtectBuy.

JCB 1 field

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

Meeza 1 field

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

Visa Secure 1 field

Field	Description
`merchantInformation.merchantDescriptor.name`	This field is required for Visa Secure travel.

These fields are required for transactions in specific countries.

Country-Specific Fields for Check Enrollment

Canada 5 fields

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

China 1 field

Field	Description
`orderInformation.shipTo.administrativeArea`	This field is required when the `orderInformation.shipTo.country` field value is `CA`, `US`, or `China`.

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`	This field is required for transactions processed in France.

United States 5 fields

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

These fields are required by specific processors for transactions.

Processor-Specific Fields for Check Enrollment

processingInformation.authorizationOptions.transactionMode string

This field is required only for merchants in Saudi Arabia.

Check Enrollment and Authorize 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": "2029",            "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"    }}

{    "_links": {        "void": {            "method": "POST",            "href": "/pts/v2/payments/7478240150646451804805/voids"        },        "self": {            "method": "GET",            "href": "/pts/v2/payments/7478240150646451804805"        }    },    "clientReferenceInformation": {        "code": "test"    },    "consumerAuthenticationInformation": {        "eciRaw": "05",        "authenticationTransactionId": "2BE13ZGIzjXdFfKw2Fi0",        "strongAuthentication": {            "OutageExemptionIndicator": "0"        },        "eci": "05",        "token": "Axj//wSTlWVuE5k5bxqFAAIU3YMmzhgzYM2Ce/LXc7XAKe/LXc7XZ0OnEFBWGTSTL0Yua1eAwHScqytwnMnLeNQo+xnO",        "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",        "paresStatus": "Y",        "acsReferenceNumber": "CardinalACS",        "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",        "directoryServerTransactionId": "4689476f-168b-415e-bad5-aee47a270086",        "veresEnrolled": "Y",        "threeDSServerTransactionId": "bda6f2d1-5c18-4589-a150-1e8c6e795e85",        "acsOperatorID": "MerchantACS",        "ecommerceIndicator": "vbv",        "specificationVersion": "2.2.0",        "acsTransactionId": "5bbd605d-80e4-48ef-82b5-0406774c66e3"    },    "id": "7478240150646451804805",    "orderInformation": {        "amountDetails": {            "totalAmount": "100.00",            "authorizedAmount": "100.00",            "currency": "GBP"        }    },    "paymentAccountInformation": {        "card": {            "brandName": "VISA",            "type": "001"        }    },    "paymentInformation": {        "tokenizedCard": {            "type": "001"        },        "card": {            "bin": "400000",            "type": "001"        }    },    "pointOfSaleInformation": {        "terminalId": "12345678"    },    "processorInformation": {        "paymentAccountReferenceNumber": "V0010013018036776997406844475",        "merchantNumber": "12345678",        "approvalCode": "100",        "cardVerification": {            "resultCodeRaw": "3",            "resultCode": "2"        },        "merchantAdvice": {            "code": "00",            "codeRaw": "0"        },        "networkTransactionId": "123456789012345",        "transactionId": "123456789012345",        "responseCode": "0",        "avs": {            "code": "U",            "codeRaw": "00"        }    },    "reconciliationId": "7026803030",    "status": "AUTHORIZED",    "submitTimeUtc": "2025-05-21T10:40:15Z"}

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

Card-Specific Fields for Checking Enrollment and Authorizing a Transaction

American Express SafeKey (US) 6 fields

Field	Description
`consumerAuthenticationInformation.productCode`	This field is required for American Express SafeKey (U.S.) when the product code is `AIR` for an airline purchase.
`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).

Cartes Bancaires 2 fields

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

China UnionPay 1 field

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

Discover ProtectBuy 1 field

Field	Description
`consumerAuthenticationInformation.defaultCard`	This field is recommended for Discover ProtectBuy.

JCB 1 field

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

Meeza 1 field

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

Visa Secure 1 field

Field	Description
`merchantInformation.merchantDescriptor.name`	This field is required for Visa Secure travel.

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

These are the minimum fields required when validating the customer.

Required Fields for Validating a Challenge

consumerAuthenticationInformation.authenticationTransactionId string

paymentInformation.card.type string

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

Card-Specific Fields for Validating a Challenge

American Express SafeKey (US) 3 fields

Field	Description
`consumerAuthenticationInformation.productCode`	This field is required for American Express SafeKey (US) when the product code is `AIR` for an airline purchase.
`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).

Cartes Bancaires 1 field

Field	Description
`consumerAuthenticationInformation.mcc`	This field is required when the card type is Cartes Bancaires.

Discover ProtectBuy 1 field

Field	Description
`consumerAuthenticationInformation.defaultCard`	This field is recommended for Discover ProtectBuy.

Visa Secure 1 field

Field	Description
`merchantInformation.merchantDescriptor.name`	This field is required for Visa Secure travel.

These fields are required for transactions in specific countries.

Country-Specific Fields for Validating a Challenge

Canada 3 fields

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

France 1 field

Field	Description
`consumerAuthenticationInformation.merchantScore`	This field is required for transactions processed in France.

United States 3 fields

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

Validate and Authorize 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 when combining payer authentication validation with authorization (POST /pts/v2/payments).

Example: Validate and Authorize a Transaction

{    "clientReferenceInformation": {        "code": "test"    },    "processingInformation": {        "capture": "true",        "authorizationOptions": {            "ignoreAvsResult": "true"        },        "actionList": [            "VALIDATE_CONSUMER_AUTHENTICATION"        ]    },    "paymentInformation": {        "card": {            "expirationYear": "2031",            "number": "4XXXXXXXXXXX25X3",            "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"        }    },    "consumerAuthenticationInformation": {        "authenticationTransactionId": "2b4eAa4K3H778X34Ciy0"    }}

{    "_links": {        "void": {            "method": "POST",            "href": "/pts/v2/payments/7478305945626990404807/voids"        },        "self": {            "method": "GET",            "href": "/pts/v2/payments/7478305945626990404807"        }    },    "clientReferenceInformation": {        "code": "test"    },    "consumerAuthenticationInformation": {        "indicator": "vbv",        "eciRaw": "05",        "authenticationResult": "0",        "strongAuthentication": {            "OutageExemptionIndicator": "0"        },        "authenticationStatusMsg": "Success",        "eci": "05",        "token": "Axj//wSTlWZX08jkcOTHAAIU3YMmzhgzcN2ie/LXsgSgKe/LXsgS50OnEFBWGTSTL0Yua1eAwHScqzK+nkcjhyY4wDi0",        "cavv": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",        "paresStatus": "Y",        "xid": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",        "directoryServerTransactionId": "fa628ed8-ad77-4723-b28f-91952eaca8fe",        "threeDSServerTransactionId": "71399671-8456-4c97-b056-e127622a5e26",        "specificationVersion": "2.2.0",        "acsTransactionId": "5f9fb589-08cc-4952-866d-30939868f411"    },    "id": "7478305945626990404807",    "orderInformation": {        "amountDetails": {            "totalAmount": "100.00",            "authorizedAmount": "100.00",            "currency": "GBP"        }    },    "paymentAccountInformation": {        "card": {            "brandName": "VISA",            "type": "001"        }    },    "paymentInformation": {        "tokenizedCard": {            "type": "001"        },        "card": {            "bin": "400000",            "type": "VISA"        }    },    "pointOfSaleInformation": {        "terminalId": "12345678"    },    "processorInformation": {        "paymentAccountReferenceNumber": "V0010013018036776997406844475",        "merchantNumber": "12345678",        "approvalCode": "100",        "cardVerification": {            "resultCodeRaw": "3",            "resultCode": "2"        },        "merchantAdvice": {            "code": "00",            "codeRaw": "0"        },        "networkTransactionId": "123456789012345",        "transactionId": "123456789012345",        "responseCode": "0",        "avs": {            "code": "U",            "codeRaw": "00"        }    },    "reconciliationId": "7026803874",    "status": "AUTHORIZED",    "submitTimeUtc": "2025-05-21T12:29:54Z"}

These API fields are required specifically for this use case.

Visa Secure-Specific Fields for Validating and Authorizing a Transaction

processingInformation.commerceIndicator string

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 string

This field is required when payer authentication is successful.

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

Card-Specific Fields for Validating and Authorizing a Transaction

American Express SafeKey (US) 3 fields

Field	Description
`consumerAuthenticationInformation.productCode`	This field is required for American Express SafeKey (US) when the product code is `AIR` for an airline purchase.
`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).

Cartes Bancaires 1 field

Field	Description
`consumerAuthenticationInformation.mcc`	This field is required when the card type is Cartes Bancaires.

Discover ProtectBuy 1 field

Field	Description
`consumerAuthenticationInformation.defaultCard`	This field is recommended for Discover ProtectBuy.

Visa Secure 1 field

Field	Description
`merchantInformation.merchantDescriptor.name`	This field is required for Visa Secure travel.

These fields are required for transactions in specific countries.

Country-Specific Fields for Validating and Authorizing a Transaction

Canada 3 fields

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

France 1 field

Field	Description
`consumerAuthenticationInformation.merchantScore`	This field is required for transactions processed in France.

United States 3 fields

Field	Description
`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": "2029",      "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"}

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

Card-Specific Fields for Non-Payment Authentication

American Express SafeKey (US) 6 fields

Field	Description
`consumerAuthenticationInformation.productCode`	This field is required for American Express SafeKey (U.S.) when the product code is `AIR` for an airline purchase.
`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).

Cartes Bancaires 2 fields

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

China UnionPay 1 field

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

Discover ProtectBuy 1 field

Field	Description
`consumerAuthenticationInformation.defaultCard`	This field is recommended for Discover ProtectBuy.

JCB 1 field

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

Meeza 1 field

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

Visa Secure 1 field

Field	Description
`merchantInformation.merchantDescriptor.name`	This field is required for Visa Secure travel.

These fields are required for transactions in specific countries.

Country-Specific Fields for Non-Payment Authentication

Canada 3 fields

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

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`	This field is required for transactions processed in France.

United States 3 fields

Field	Description
`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: October 28, 2026

Device Data Collection Setup

Check Enrollment

Check Enrollment and Authorize a Transaction

Validate a Challenge

Validate and Authorize a Transaction

Non-Payment Authentication

Not available for your audience