Checking Enrollment When Using a TMS Token {#pa2-check-enroll-token-use-intro} ============================================================================== Running 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 demostrates this process while using a TMS token. Card-Specific Requirements -------------------------- Some payment cards require additional information to be collected during a transaction. [consumerAuthenticationInformation. defaultCard](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-default-card.md "") : This field is recommended for Discover ProtectBuy. [consumerAuthenticationInformation.mcc](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-mcc.md "") : This field is required when the card type is Cartes Bancaires. [consumerAuthenticationInformation. productCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-product-code.md "") : This field is required for American Express SafeKey (US) when the product code is `AIR` for an airline purchase. [merchantInformation.merchantDescriptor. name](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-name.md "") : This field is required for Visa Secure travel. [orderInformation.shipTo.addess1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-shipto-address1.md "") : This field is required only for American Express SafeKey (US). {#pa2-check-enroll-token-use-intro_dl_d1v_trz_rxb} [orderInformation.shipTo.address2](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-shipto-address2.md "") : This field is required only for American Express SafeKey (US.) [orderInformation.shipTo.administrativeArea](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-shipto-administrative-area.md "") : This field is required only for American Express SafeKey (US). [orderInformation.shipTo.country](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-shipto-country.md "") : This field is required only for American Express SafeKey (US). [orderInformation.shipTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-shipto-postal-code.md "") : This field is required for American Express SafeKey (US). [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-card-type.md "") : : This field is required when the card type is Cartes Bancaires, JCB, China UnionPay, or Meeza. Country-Specific Requirements ----------------------------- These fields are required for transactions in specific countries. [consumerAuthenticationInformation. merchantScore](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-merchant-score.md "") : This field is required for transactions processed in France. [consumerAuthenticationInformation. overrideCountryCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-override-country-code.md "") : 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](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/merch-info-aa/merch-info-merchant-descriptor-country-a.md "") : 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](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-admin-area.md "") : This field is required for transactions in the US and Canada. [orderinformation.billTo.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-locality.md "") : This field is required for transactions in the US and Canada. [orderInformation.billTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : This field is required when the orderInformation.billTo.country field value is `US` or `CA`. {#pa2-check-enroll-token-use-intro_dl_gpf_5rz_rxb} [orderInformation.shipTo.administrativeArea](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-shipto-county.md "") : This field is required when the orderInformation.shipTo.country field value is `CA` or `US`. [orderInformation.shipTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-shipto-postal-code.md "") : This field is required when the orderInformation.shipTo.country field value is `US` or `CA`. Processor-Specific Requirements {#pa2-check-enroll-token-use-intro_section_kl3_tbh_xwb} --------------------------------------------------------------------------------------- These fields are required by specific processors for transactions. [processingInformation.authorizationOptions. transactionMode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/processing-info-aa/processing-info-auth-ops-transaction-mode.md "") : This field is required only for merchants in Saudi Arabia. Endpoint -------- **Production:** `POST ``https://api.cybersource.com``/risk/v1/authentications` **Test:** `POST ``https://apitest.cybersource.com``/risk/v1/authentications` Required Fields for Checking Enrollment in Payer Authentication While Using a TMS Token {#pa2-use-enroll-token-tms-reqd-fields} =============================================================================================================================== These fields are the minimum fields required for verifying that a customer is enrolled in a payer authentication program. It doesn't matter if the enrollment check is frictionless or results in a challenge, the same fields are required in the request. The fields in the response will differ. Required Fields --------------- [consumerAuthenticationInformation.deviceChannel](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-device-channel.md "") : [consumerAuthenticationInformation.referenceId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/cons-auth-info-aa/cons-auth-info-reference-id.md "") : [paymentInformation.customer.customerId](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-customer-customer-id.md "") : [deviceInformation.httpAcceptBrowserValue](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-http-accept-browser-value.md "") : [deviceInformation.httpAcceptContent](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-http-accept-content.md "") : [deviceInformation.httpBrowserColorDepth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-http-browser-color-depth.md "") : [deviceInformation.httpBrowserJavaEnabled](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-http-browser-java-enabled.md "") : [deviceInformation.httpBrowserJavaScript Enabled](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-http-browser-java-script-enabled.md "") : [deviceInformation.httpBrowserLanguage](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-http-browser-language.md "") : [deviceInformation.httpBrowserScreenHeight](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-http-browser-screen-height.md "") : [deviceInformation.httpBrowserScreenWidth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-http-browser-screen-width.md "") : [deviceInformation.httpBrowserTimeDif ference](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-http-browser-time-diff.md "") : [deviceInformation.ipAddress](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-ip-address.md "") : [deviceInformation.userAgentBrowserValue](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/device-info-aa/device-info-http-user-agent-browser-value.md "") : When the customer's browser provides this value, you must include that value in your request. [orderInformation.amountDetails.currency](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-currency.md "") : [orderInformation.amountDetails.totalAmount](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-amount-details-total-amount.md "") : This field is required when the orderInformation.lineItems.unitPrice field is not used. [orderInformation.billTo.address1](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address1.md "") : [orderInformation.billTo.address2](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-address2.md "") : [orderInformation.billTo.administrativeArea](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-admin-area.md "") : This field is required for the US and Canada. [orderInformation.billTo.country](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-country.md "") : This field is required for the US and Canada. [orderInformation.billTo.email](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-email.md "") : [orderInformation.billTo.firstName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-first-name.md "") : [orderInformation.billTo.lastName](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-last-name.md "") : [orderinformation.billTo.locality](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-locality.md "") : [orderInformation.billTo.phoneNumber](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : [orderInformation.billTo.postalCode](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/order-info-aa/order-info-bill-to-postal-code.md "") : [paymentInformation.card.expirationYear](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-year.md "") : [paymentInformation.card.expirationMonth](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-exp-mo.md "") : [paymentInformation.card.type](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/payment-info-aa/payment-info-card-type-a.md "") : Related Information ------------------- * [API field reference guide for the REST API](https://developer.cybersource.com/docs/cybs/en-us/api-fields/reference/all/rest/api-fields/rest-api-fields-intro.md "") REST Example: Checking Enrollment When Using a TMS Token {#pa2-use-token-tms-enroll-frictionlesx-rest-ex} ========================================================================================================= Request ``` { "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": "test@email.com", "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" } } ``` Frictionless Response to Request ``` { "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" } ``` Challenge Response to Request ``` { "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": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI0ZTUwZjU4Ni1iMTVjLTRjMDMtYTE4Ni1lYWZiNDBkNTBiODAiLCJhY3NUcmFuc0lEIjoiMzg4OGUxNTMtNmI5Ny00ZjQzLWFmZWUtNjA1MjdjMmUwYjkxIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0", "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" } ```