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

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:

  1. Use Cardinal SDK to display the challenge

  2. Handle user interaction (OTP, biometric, etc.)

  3. Collect the challenge result

  4. Proceed to validation endpoint

Device Data Collection

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

PreviousSetupNextValidate

Last updated

Was this helpful?