# Check enroll

### Endpoint Details

**Method:** `POST`\
**URL:** <mark style="color:purple;">`/v1/risk/authentication/enroll`</mark>\
**Purpose:** Check card enrollment in 3D Secure and perform authentication

### Headers

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

### Request Body

```json
{
  "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

<table><thead><tr><th width="309.68359375">Field</th><th width="83.36328125">Type</th><th width="119.0703125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>transaction_info.type</code></td><td>string</td><td>Yes</td><td>Must be "check_enroll"</td></tr><tr><td><code>transaction_info.reference_code</code></td><td>string</td><td>Yes</td><td>Unique transaction reference code</td></tr><tr><td><code>card</code></td><td>object</td><td>Yes</td><td>Card information (same formats as setup)</td></tr><tr><td><code>order_info.amount_details</code></td><td>object</td><td>Yes</td><td>Transaction amount and currency</td></tr><tr><td><code>bill_to</code></td><td>object</td><td>Yes</td><td>Billing information</td></tr><tr><td><code>buyer_info</code></td><td>object</td><td>Yes</td><td>Additional buyer information</td></tr><tr><td><code>device_info</code></td><td>object</td><td>Yes</td><td>Device information from Cardinal Songbird SDK</td></tr><tr><td><code>authentication.reference_id</code></td><td>string</td><td>Yes</td><td>Reference ID from setup response</td></tr><tr><td><code>authentication.token</code></td><td>string</td><td>Yes</td><td>Token from setup response</td></tr><tr><td><code>authentication.return_url</code></td><td>string</td><td>Yes</td><td>URL to redirect after authentication</td></tr><tr><td><code>authentication.device_channel</code></td><td>string</td><td>Yes</td><td>Device channel (usually "Browser")</td></tr><tr><td><code>authentication.mode</code></td><td>string</td><td>Yes</td><td>Authentication mode</td></tr></tbody></table>

### 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

{% tabs %}
{% tab title="Authentication Successful (Frictionless)" %}

```json
{
    "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"
        }
    }
}
```

{% endtab %}

{% tab title="Authentication Pending (Challenge Required)" %}

```json
{
  "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"
    }
  }
}
```

{% endtab %}

{% tab title="Authentication Failed" %}

```json
{
  "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"
    }
  }
}
```

{% endtab %}
{% endtabs %}

### 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&#x20;

<table><thead><tr><th width="274.5078125">Field</th><th width="471.11328125">Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>Always "check_enroll_response"</td></tr><tr><td><code>transaction_id</code></td><td>Unique transaction identifier</td></tr><tr><td><code>reference_code</code></td><td>Your original reference code</td></tr><tr><td><code>request_id</code></td><td>Unique request identifier</td></tr><tr><td><code>status</code></td><td>"Authentication_successful", "Pending_authentication", or "Authentication_failed"</td></tr><tr><td><code>created_at</code></td><td>ISO 8601 timestamp of creation</td></tr></tbody></table>

#### card

<table><thead><tr><th width="274.5078125">Field</th><th width="368.41796875">Description</th></tr></thead><tbody><tr><td><code>bin</code></td><td>Bank Identification Number (first 6 digits)</td></tr><tr><td><code>type</code></td><td>Card network (VISA, MASTERCARD, AMEX)</td></tr></tbody></table>

#### 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)

<table><thead><tr><th width="274.5078125">Field</th><th width="368.41796875">Description</th></tr></thead><tbody><tr><td><code>reason</code></td><td>Error code</td></tr><tr><td><code>message</code></td><td>Detailed error description</td></tr></tbody></table>

#### 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

```json
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.