Check enroll

Verifies if the card is enrolled in 3-D Secure and initiates the authentication challenge if required.

Endpoint Details

Method: POST URL: /v1/risk/authentication/enroll Purpose: Check card enrollment in 3D Secure and perform authentication

Headers

Content-Type: application/json
x-api-key: <YOUR_API_KEY>

Request Body

{
  "transaction_info": {
    "type": "check_enroll",
    "reference_code": "123456789"
  },
  "card": {
    "number": "{{token_id : detokenize}}",
    "expiration_date": "{{token_id : detokenize}}"
  },
  "order_info": {
    "amount_details": {
      "total_amount": "1000",
      "currency": "MXN"
    }
  },
  "bill_to": {
    "first_name": "John",
    "last_name": "Doe",
    "country": "US",
    "address_1": "1 Market St",
    "address_2": "Suite 200",
    "city": "san francisco",
    "state": "CA",
    "phone_number": "4158880000",
    "email": "accept@gmsectec.com",
    "postal_code": "94105"
  },
  "buyer_info": {
    "mobile_phone": "4158880000"
  },
  "device_info": {
    "ip_address": "190.123.237.237",
    "http_browser_color_depth": "30",
    "http_browser_java_enabled": false,
    "http_browser_js_enabled": true,
    "http_browser_screen_height": "1117",
    "http_browser_screen_width": "1728",
    "http_browser_time_offset": "240",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
    "cookies_accepted": true,
    "http_browser_language": "en-US",
    "http_accept_content": "application/json"
  },
  "authentication": {
    "reference_id": "21db503f-1eb5-4a77-81e8-1129c4106af3",
    "return_url": "https://merchant.com/returnUrl",
    "device_channel": "Browser",
    "mode": "S",
    "token": "AxixbwSTl1LdGx33S/NFAU9+ZWgkZAKH0MmkmXoxkcwdAJgAOBao"
  }
}

Parameters

Field

Type

Required

Description

transaction_info.type

string

Yes

Must be "check_enroll"

transaction_info.reference_code

string

Yes

Unique transaction reference code

card

object

Yes

Card information (same formats as setup)

order_info.amount_details

object

Yes

Transaction amount and currency

bill_to

object

Yes

Billing information

buyer_info

object

Yes

Additional buyer information

device_info

object

Yes

Device information from Cardinal Songbird SDK

authentication.reference_id

string

Yes

Reference ID from setup response

authentication.token

string

Yes

Token from setup response

authentication.return_url

string

Yes

URL to redirect after authentication

authentication.device_channel

string

Yes

Device channel (usually "Browser")

authentication.mode

string

Yes

Authentication mode

Device Information

The device_info object contains information collected from the Cardinal Songbird SDK implemented on your frontend. This includes:

Browser characteristics and capabilities
Screen resolution and color depth
Device timezone and language settings
JavaScript and cookie support
IP geolocation data

Response Structure

The API returns a standardized response:

status: string - "success", "fail" or "error"
message: string - Short description about the status
data: object - Authentication information and transaction details

Response Examples

{
    "status": "success",
    "message": "Check enroll successful, authentication succeded",
    "data": {
        "transaction_info": {
            "type": "check_enroll_response",
            "transaction_id": "0001733254043705804760",
            "reference_code": "3b6c483b-5bc1-4869-9c36-c637d22aa9ba",
            "request_id": "7332540438306064704953",
            "status": "Authentication_successful",
            "created_at": "2024-12-03T19:27:24Z"
        },
        "card": {
            "bin": "400000",
            "type": "VISA"
        },
        "consumer_auth_info": {
            "eci": "05",
            "eci_raw": "05",
            "token": "AxjzbwSTjX9wtyzUECW5AIcBT342XjgZ5COGoEPKGTSTL0YuMA/gDgAA5ghU",
            "commerce_indicator": "vbv",
            "pares_status": "Y",
            "veres_enrolled": "Y",
            "acs_transaction_id": "10373298-d099-415a-822b-37ae11d22d92",
            "authentication_transaction_id": "JRc2YtrR7mb3qXsPgDq0",
            "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
            "specificationVersion": "2.2.0",
            "tree_dss_server_transaction_id": "83449f1b-12d1-4b47-b7a0-c507cc52ef22",
            "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
            "directory_server_transaction_id": "1711623f-b308-4f98-bf06-41fa29f4744d",
            "acs_reference_number": "Cardinal ACS"
        }
    }
}

{
  "status": "success",
  "message": "Check enroll successful, authentication pending",
  "data": {
    "transaction_info": {
      "type": "check_enroll_response",
      "transaction_id": "0001751379824238068542",
      "reference_code": "02ea9573-3ef1-450c-8a46-e459cb63d678",
      "request_id": "7513798247296474004806",
      "status": "Pending_authentication",
      "created_at": "2025-07-01T14:23:45Z"
    },
    "card": {
      "bin": "520000",
      "type": "MASTERCARD"
    },
    "error": {
      "reason": "Consumer_authentication_required",
      "message": "The cardholder is enrolled in Payer Authentication. Please authenticate the cardholder before continuing with the transaction."
    },
    "consumer_auth_info": {
      "token": "AxjxbwSTl1Ll0BtbA71GAk9+ZWiJyKojhqBQ+Xa0ky9GMjmDoBcAgllj",
      "pares_status": "C",
      "veres_enrolled": "Y",
      "acs_transaction_id": "406d1307-d60b-49fe-8d39-ca48514b66f0",
      "acs_url": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",
      "authentication_transaction_id": "DKjne4MBXRSsa1fryRE0",
      "challenge_required": "N",
      "pareq": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiIxYWM3MzM0Yy0zOGFhLTRhNTQtOTljMC0wOGMyMTRkOGQ2OTAiLCJhY3NUcmFuc0lEIjoiNDA2ZDEzMDctZDYwYi00OWZlLThkMzktY2E0ODUxNGI2NmYwIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0",
      "specificationVersion": "2.1.0",
      "stepup_url": "https://centinelapistag.cardinalcommerce.com/V2/Cruise/StepUp",
      "tree_dss_server_transaction_id": "1ac7334c-38aa-4a54-99c0-08c214d8d690",
      "directory_server_transaction_id": "1ccf8e46-c86e-42b1-9791-e54d4315b44b",
      "acs_reference_number": "CardinalACS"
    }
  }
}

{
  "status": "success",
  "message": "Check enroll successful, authentication failed",
  "data": {
    "transaction_info": {
      "type": "check_enroll_response",
      "transaction_id": "0001751380613267024066",
      "reference_code": "cc02cc3f-3226-43ee-89ab-a2770b7f6396",
      "request_id": "7513806135126212604807",
      "status": "Authentication_failed",
      "created_at": "2025-07-01T14:36:53Z"
    },
    "card": {
      "bin": "400000",
      "type": "VISA"
    },
    "consumer_auth_info": {
      "eci_raw": "07",
      "token": "AxjxbwSTl1MB1gvUofOHAU9+ZWlh3KojhqBQ+Xc0ky9GMjmDoBUAgVmF",
      "pares_status": "R",
      "veres_enrolled": "Y",
      "acs_transaction_id": "fb023de3-1e75-4c52-9a49-58e20b4d1d23",
      "authentication_transaction_id": "mE2IhZxZLCAVxbMn3it0",
      "signed_pares_status_reason": "01",
      "specificationVersion": "2.2.0",
      "tree_dss_server_transaction_id": "e1e64d48-e354-44d3-b644-8064e790b200",
      "directory_server_transaction_id": "50b05dab-c21d-4fb8-863d-997c2934a666",
      "acs_reference_number": "CardinalACS"
    }
  }
}

ECI (Electronic Commerce Indicator) Codes

The ECI codes indicate the authentication result:

Mastercard

01 and 02: Authentication successful (accepted)
00: Authentication failed (rejected)

VISA / AMEX

05 and 06: Authentication successful (accepted)
07: Authentication failed (rejected)

Note: For Mastercard, only eci_raw is returned. For VISA/AMEX, both eci and eci_raw are returned with the same value.

Response Fields

transaction_info

Field

Description

type

Always "check_enroll_response"

transaction_id

Unique transaction identifier

reference_code

Your original reference code

request_id

Unique request identifier

status

"Authentication_successful", "Pending_authentication", or "Authentication_failed"

created_at

ISO 8601 timestamp of creation

card

Field

Description

bin

Bank Identification Number (first 6 digits)

type

Card network (VISA, MASTERCARD, AMEX)

consumer_auth_info

Common Fields (all scenarios)

Field

Description

token

Updated authentication token

acs_transaction_id

Access Control Server transaction ID

authentication_transaction_id

Critical - Use this ID in validate endpoint

specificationVersion

3D Secure version (2.1.0, 2.2.0)

tree_dss_server_transaction_id

Directory Server transaction ID

directory_server_transaction_id

Directory Server transaction ID

acs_reference_number

ACS reference identifier

Success Scenario Fields

eci

Electronic Commerce Indicator (VISA/AMEX only)

eci_raw

Raw ECI value (all card types)

commerce_indicator

Commerce type (vbv, spa, etc.)

pares_status

Authentication status: Y=Authenticated, N=Not authenticated, C=Challenge

veres_enrolled

Enrollment status: Y=Enrolled, N=Not enrolled

cavv

Cardholder Authentication Verification Value

xid

Transaction identifier for VISA/AM

Pending Scenario Fields

Field

Description

pares_status

C = Challenge required

veres_enrolled

Y = Enrolled in 3D Secure

acs_url

URL for challenge processing

challenge_required

N/Y indicator

pareq

Base64 encoded challenge request

stepup_url

Cardinal step-up URL for challenge

Failed Scenario Fields

Field Name

Description

eci_raw

Failure ECI code (07 for VISA/AMEX, 00 for Mastercard)

pares_status

R=Rejected, N=Not authenticated

signed_pares_status_reason

Reason code for failure

error Object (pending scenario)

Field

Description

reason

Error code

message

Detailed error description

Scenario 1: Authentication Successful

Status: Authentication_successful
Action: Proceed directly to payment authorization
ECI Codes: 01/02 (Mastercard), 05/06 (VISA/AMEX)

Scenario 2: Challenge Required

Status: Pending_authentication
Action: Display Cardinal Commerce challenge modal
Next Step: Call Validate endpoint after challenge completion

Scenario 3: Authentication Failed

Status: Authentication_failed
Action: Handle according to merchant policy
ECI Codes: 00 (Mastercard), 07 (VISA/AMEX)

Usage Example

cURL

curl --location 'https://api.firstoken.co/v1/risk/authentication/enroll' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
  "transaction_info": {
    "type": "check_enroll",
    "reference_code": "123456789"
  },
  "card": {
    "number": "4111111111111111",
    "expiration_date": "01/25"
  },
  "order_info": {
    "amount_details": {
      "total_amount": "1000",
      "currency": "USD"
    }
  },
  "bill_to": {
    "first_name": "John",
    "last_name": "Doe",
    "country": "US",
    "address_1": "1 Market St",
    "city": "San Francisco",
    "state": "CA",
    "phone_number": "4158880000",
    "email": "accept@gmsectec.com",
    "postal_code": "94105"
  },
  "authentication": {
    "reference_id": "21db503f-1eb5-4a77-81e8-1129c4106af3",
    "return_url": "https://merchant.com/returnUrl",
    "device_channel": "Browser",
    "mode": "S",
    "token": "AxixbwSTl1LdGx33S/NFAU9+ZWgkZAKH0MmkmXoxkcwdAJgAOBao"
  }
}'

Next Steps

Based on the response status:

If Authentication Successful

Proceed to payment authorization with the authentication data
Use ECI codes and CAVV for liability shift

If Challenge Required

Display Cardinal Commerce challenge modal to user
After user completes challenge, call the Validate Authentication endpoint
Use the authentication_transaction_id from this response

If Authentication Failed

Handle according to your business policy
Consider declining the transaction or offering alternative payment methods

Integration Notes

Cardinal Commerce SDK

When status is Pending_authentication, you need to:

Use Cardinal SDK to display the challenge
Handle user interaction (OTP, biometric, etc.)
Collect the challenge result
Proceed to validation endpoint

Device Data Collection

Ensure proper implementation of Cardinal Songbird SDK for accurate device fingerprinting data collection.

PreviousSetup NextValidate

Last updated 7 months ago

hashtagEndpoint Details

hashtagHeaders

hashtagRequest Body

hashtagParameters

hashtagDevice Information

hashtagResponse Structure

hashtagResponse Examples

hashtagECI (Electronic Commerce Indicator) Codes

hashtagMastercard

hashtagVISA / AMEX

hashtagResponse Fields

hashtagtransaction_info

hashtagcard

hashtagconsumer_auth_info

hashtagerror Object (pending scenario)

hashtagScenario 1: Authentication Successful

hashtagScenario 2: Challenge Required

hashtagScenario 3: Authentication Failed

hashtagUsage Example

hashtagcURL

hashtagNext Steps

hashtagIf Authentication Successful

hashtagIf Challenge Required

hashtagIf Authentication Failed

hashtagIntegration Notes

hashtagCardinal Commerce SDK

hashtagDevice Data Collection

Endpoint Details

Headers

Request Body

Parameters

Device Information

Response Structure

Response Examples

ECI (Electronic Commerce Indicator) Codes

Mastercard

VISA / AMEX

Response Fields

transaction_info

card

consumer_auth_info

error Object (pending scenario)

Scenario 1: Authentication Successful

Scenario 2: Challenge Required

Scenario 3: Authentication Failed

Usage Example

cURL

Next Steps

If Authentication Successful

If Challenge Required

If Authentication Failed

Integration Notes

Cardinal Commerce SDK

Device Data Collection