Use Case: Checking Enrollment in Payer Authentication While Using a Stored Payment Credential (TMS Token)

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 example includes using a token during the process.

Card-Specific Requirements

Some payment cards require information to be collected during a transaction.
This field is recommended for Discover ProtectBuy.
This field is required when the card type is Cartes Bancaires.
This field is required for American Express SafeKey (US) when the product code is
AIR
 for an airline purchase.
This field is required for Visa Secure travel.
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US.)
This field is required only for American Express SafeKey (US).
This field is required only for American Express SafeKey (US).
This field is required for American Express SafeKey (US).
This field is required when the card type is Cartes Bancaires, JCB, UPI, or Meeza.

Country-Specific Requirements

These fields are required for transactions in specific countries.
This field is required for transactions processed in France.
For Meeza transactions, this value must be set to
EG
 if Egypt was not set as the country in the merchant configuration during merchant onboarding.
For Meeza transactions, this value must be set to
EG
 if Egypt was not set as the country in the merchant configuration during merchant onboarding.
This field is required for transactions in the US, Canada, and Mainland China.
This field is required for transactions in the US, Canada, and Mainland China.
This field is required when the
orderInformation.billTo.country
 field value is
US
 or
CA
.
This field is required when the
orderInformation.shipTo.country
 field value is
CA
,
US
, or
China
.
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.
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 Stored Payment Credential (TMS Token)

These fields are the minimum fields required for verifying that a customer is enrolled in a payer authentation program. Under certain circumstances, a field that normally is optional might be required. The circumstance that makes an optional field required is noted.
For Meeza transactions, this value must be set to
EG
if Egypt was not set as the country in the merchant configuration during the merchant onboarding.
For Meeza transactions, this value must be set to
EG
if Egypt was not set as the country in the merchant configuration during merchant onboarding.
This field is required when the
orderInformation.lineItems.unitPrice
field is not used.
This field is required for the US, Canada, and Mainland China.
This field is required for the US, Canada, and Mainland China. For Mainland China, use the ISO 3166-2 format.
This field is required when the
paymentInformation.card.number
field is included.
This field is required when the
paymentInformation.card.number
field is included.
This field is strongly recommended.
This field is used with network tokens.
This field is used with network tokens.
This field is carries the network token information.
This field is used with network tokens.
This field is used with network tokens.

Optional Fields for Checking Enrollment in Payer Authentication

These fields are usually optional when verifying enrollment for a Payer Authentication transaction. In certain circumstances, the information provided by an optional field might be required before a transaction can proceed. Those optional fields that are sometimes required are also listed as required fields with the circumstance described.
IMPORTANT
The fields that are marked with a single asterisk (*) in front are browser-related fields. The information collected by these browser-related fields, while not required, is highly recommended for all EMV 3-D Secure transactions.
IMPORTANT
The fields that are marked with a double asterisk (**) at the end will be required as part of the EMV 3-D Secure 2.x minimum data requirements for Visa Secure. These conditionally optional fields will be removed from the optional fields list and moved to the required list on August 12, 2024.
Required (when available) unless market or regional mandate restricts sending this information.
Required (when available) unless market or regional mandate restricts sending this information.
WARNING
Modifying this field could affect liability shifts down the payment chain. Unless you are very familiar with the various types of authentication, do not change the default settings before consulting with customer support.
Recommended for Discover ProtectBuy.
Recommended for Discover ProtectBuy.
Recommended for Discover ProtectBuy.
When the customer’s browser provides a value, you must include that value in your request.
Required (when available) unless market or regional mandate restricts sending this information.
Strongly recommended.
Strongly recommended.
When this field is empty, the current date is used.
riskInformation.buyerHistory.transaction CountDay
Recommended for Discover ProtectBuy. Contact customer support for more information about this field.
riskInformation.buyerHistory.transaction CountYear
Recommended for Discover ProtectBuy. Contact customer support for more information about this field.
riskInformation.buyerHistory.accountPur chases
Contact customer support for more information about this field.
riskInformation.buyerHistory.addCard Attempts
Recommended for Discover ProtectBuy. Contact customer support for more information about this field.
riskInformation.buyerHistory.customer Account.createDate
Recommended for Discover ProtectBuy. Contact customer support for more information about this field.
riskInformation.buyerHistory.customerAc count.lastChangeDate
Recommended for Discover ProtectBuy. Contact customer support for more information about this field.
riskInformation.buyerHistory.customerAc count.passwordChangeDate
Recommended for Discover ProtectBuy. Contact customer support for more information about this field.
riskInformation.buyerHistory.customerAc count.shipAddressUsageDate
Contact customer support for more information about this field.
riskInformation.buyerHistory.paymentAc countDate
Contact customer support for more information about this field.
riskInformation.buyerHistory.priorSuspic iousActivity
Contact customer support for more information about this field.
riskInformation.buyerHistory.transaction CountDay
Contact customer support for more information about this field.
riskInformation.buyerHistory.transaction CountYear
Contact customer support for more information about this field.
java.io.PrintWriter@1e5c4291
travelInformation.passengers.firstName

REST Example: Checking Enrollment While Using a Token

Endpoint

Production:
POST
https://api.cybersource.com
/risk/v1/authentication
Test:
POST
https://apitest.cybersource.com
/risk/v1/authentication
Request 
    
{
    "orderInformation": {
        "amountDetails": {
            "currency": "USD",
            "totalAmount": "10.99"
        },
        "billTo": {
            "address1": "901 metro center blvd",
            "address2": "metro 3",
            "administrativeArea": "CA",
            "country": "US",
            "locality": "san francisco",
            "firstName": "John",
            "lastName": "Doe",
            "phoneNumber": "4158880000",
            "postalCode": "94404",
            "email": "test@email.com"
        }
    },
    "paymentInformation": {
        "card": {
            "expirationMonth": "05",(Required)
            "expirationYear": "2029" (Required)
        }
    },
    "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"
    }
}
Response to a Successful Request 
    
{
    "consumerAuthenticationInformation": {
        "eciRaw": "05",
        "authenticationTransactionId": "1uYPvYpKtpKafAp05J10",
        "strongAuthentication": {
           "OutageExemptionIndicator": "0"
        },
        "eci": "05",
        "token": "AxjzbwSThBz8GGbMi0LEAG8BT34OR7yfSBcS0CqGTSTL0Yvue1AHgAAAWRZ8",
        "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
        "paresStatus": "Y",
        "acsReferenceNumber": "Cardinal ACS",
        "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
        "directoryServerTransactionId": "2e098b7f-a71a-4108-be81-a0b7ea640068",
        "veresEnrolled": "Y",
        "threeDSServerTransactionId": "6f3bf625-4643-4952-a654-2c73d75e2a2f",
        "acsOperatorID": "MerchantACS",
        "ecommerceIndicator": "vbv",
        "specificationVersion": "2.1.0",
        "acsTransactionId": "5333668d-a07c-49df-9e9a-3f2d8e08cefe"
        },
        "id": "7159425271756296504004",
        "paymentInformation": {
           "card": {
           "bin": "400009",
           "type": "VISA"
        }
   },
   "status": "AUTHENTICATION_SUCCESSFUL",
   "submitTimeUtc": "2024-05-17T10:42:07Z"
}

Simple Order Example: Checking Enrollment Using a Token

Request 
    
billTo_city=Mountain View
billTo_country=US
billTo_email=test@yahoo.com
billTo_firstName=Tanya
billTo_lastName=Lee
billTo_postalCode=94043
billTo_state=CA
billTo_street1=1234 Gold Ave
card_cardType=001
card_cvNumber=111
card_expirationMonth=12
card_expirationYear=2030
ccAuthService_run=true
merchantID=patest
merchantReferenceCode=0001
payerAuthEnrollService_referenceID=f13fe5e0-9b47-4ea1-a03a-ec360f4d0f9f
payerAuthEnrollService_returnURL=https://example.com/step-up-return-url.jsp
payerAuthEnrollService_run=true
purchaseTotals_currency=USD
purchaseTotals_grandTotalAmount=30.00
recurringSubscriptionInfo_subscriptionID=uff9-hb498gu498
Response to a Successful Request 
    
decision=REJECT
merchantReferenceCode=0001
payerAuthEnrollReply_accessToken=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJqdGkiOiI1MDc4OTI0Mi0z YmEzLTRhZTItYWQwOS1kZjZkODk2NWQ5MjciLCJpYXQiOjE1OTgyOTk1MjQsImlzcyI6IjVkZDgzYmYwMGU0MjNk MTQ5OGRjYmFjYSIsImV4cCI6MTU5ODMwMzEyNCwiT3JnVW5pdElkIjoiNTVlZjNmMTBmNzIzYWE0MzFjOTliNWViIi wiUGF5bG9hZCI6eyJBQ1NVcmwiOiJodHRwczovLzBtZXJjaGFudGFjc3N0YWcuY2FyZGluYWxjb21tZXJjZS5jb20 vTWVyY2hhbnRBQ1NXZWIvY3JlcS5qc3AiLCJQYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDS nRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNaTR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUkzT kRNeVlUWXdNQzA0TXpNMkxUUm1PRGN0WVdKbE9TMDJObVkzTkRFM01EaGhNV1FpTENKaFkzTlVjbUZ1YzBsRUlqb 2lPR0U1TkRkaU9ETXRNRFJpTkMwMFltVmlMV0V5WWpNdFpHTmpNV0UxWmprMFlURXlJaXdpWTJoaGJHeGxibWRsVj JsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJUcmFuc2FjdGlvbklkIjoiVEQ1b1MwbzFGQzY1cWF2MHhzeDAifS wiT2JqZWN0aWZ5UGF5bG9hZCI6dHJ1ZSwiUmV0dXJuVXJsIjoiaHR0cHM6Ly9leGFtcGxlLmNvbS9zdGVwLXV wLXJldHVybi11cmwuanNwIn0.8wZ8XhLgOIIRvgEUugvYrRAi-efavZTNM0tWInYLTfE
payerAuthEnrollReply_acsTransactionID=8a947b83-04b4-4beb-a2b3-dcc1a5f94a12
payerAuthEnrollReply_acsURL=https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp
payerAuthEnrollReply_authenticationTransactionID=TD5oS0o1FC65qav0xsx0
payerAuthEnrollReply_cardBin=40000000
payerAuthEnrollReply_cardTypeName=VISA
payerAuthEnrollReply_challengeRequired=false
payerAuthEnrollReply_directoryServerTransactionID=395fb036-cfc6-462b-b28d-d6ed7c970cdd
payerAuthEnrollReply_paReq=eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMi4wIiwidGhy ZWVEU1NlcnZlclRyYW5zSUQiOiI3NDMyYTYwMC04MzM2LTRmODctYWJlOS02NmY3NDE3MDhhMWQiLCJhY3NU cmFuc0lEIjoiOGE5NDdiODMtMDRiNC00YmViLWEyYjMtZGNjMWE1Zjk0YTEyIiwiY2hhbGxlbmdlV2luZG93U2l 6ZSI6IjAyIn0
payerAuthEnrollReply_reasonCode=475
payerAuthEnrollReply_specificationVersion=2.2.0
payerAuthEnrollReply_stepUpUrl=https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp
payerAuthEnrollReply_threeDSServerTransactionID=7432a600-8336-4f87-abe9-66f741708a1d
payerAuthEnrollReply_veresEnrolled=Y
reasonCode=475
requestID=5982995245816268803007
requestToken=AxjzbwSTRFa9DM1xnUu/ABEBURwlqsQ5pAy7gDtXb0kyro9JLIYA8AAA2wK2