> For the complete documentation index, see [llms.txt](https://firstoken.gitbook.io/api-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://firstoken.gitbook.io/api-docs/api-reference/risk/payer-authentication-3d-secure/endpoints/validate.md).

# Validate

### Endpoint Details

**Method:** `POST`\
**URL:** <mark style="color:purple;">`/v1/risk/authentication/validate`</mark>\
**Purpose:** Validate authentication results after user challenge completion

### When to Use

This endpoint is **only used** when the Check Enrollment response has:

* **Status**: `Pending_authentication`
* **Message**: "Check enroll successful, authentication pending"

### Headers

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

### Request Body

```json
{
    "transaction_info": {
        "type": "validate_result",
        "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"
    },
    "authentication": {
        "transaction_id": "DKjne4MBXRSsa1fryRE0"
    }
}
```

### Parameters

<table><thead><tr><th width="314.1015625">Field</th><th width="87.07421875">Type</th><th width="84.54296875">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 "validate_result".</td></tr><tr><td><code>transaction_info.reference_code</code></td><td>string</td><td>Yes</td><td>Original transaction reference code.</td></tr><tr><td><code>card</code></td><td>object</td><td>Yes</td><td>Same card information as check_enroll.</td></tr><tr><td><code>order_info</code></td><td>object</td><td>Yes</td><td>Same order information as check_enroll.</td></tr><tr><td><code>bill_to</code></td><td>object</td><td>Yes</td><td>Same billing information as check_enroll.</td></tr><tr><td><code>authentication.transaction_id</code></td><td>string</td><td>Yes</td><td>Authentication transaction ID from check</td></tr></tbody></table>

### Critical Parameter

#### authentication.transaction\_id

**This field must be the exact value from:**

```json
consumer_auth_info.authentication_transaction_id
```

**From the Check Enrollment response.**

**Example:** If Check Enrollment returned:

```json
{
  "consumer_auth_info": {
      "authentication_transaction_id": "DKjne4MBXRSsa1fryRE0"
      ...
  }
}
```

Then use in Validate:

```json
{
  "authentication": {
      "transaction_id": "DKjne4MBXRSsa1fryRE0"
  }
}
```

***

### 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="Validation Successful" %}

```json
{
  "status": "success",
  "message": "Validation successful, authentication succeded",
  "data": {
    "transaction_info": {
      "type": "validate_result_response",
      "reference_code": "02ea9573-3ef1-450c-8a46-e459cb63d678",
      "request_id": "7513798812266365904805",
      "status": "Authentication_successful",
      "created_at": "2025-07-01T14:24:41Z"
    },
    "card": {
      "bin": "520000",
      "type": "MASTERCARD"
    },
    "consumer_auth_info": {
      "eci_raw": "02",
      "token": "AxjxbwSTl1Ln0fGouuelAk9+ZWihgKojhqBQ+hk0ky9GMjmDoBcAz1jA",
      "pares_status": "Y",
      "acs_transaction_id": "406d1307-d60b-49fe-8d39-ca48514b66f0",
      "specificationVersion": "2.1.0",
      "tree_dss_server_transaction_id": "1ac7334c-38aa-4a54-99c0-08c214d8d690",
      "ucaf_authentication_data": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
      "ucaf_collection_indicator": "2",
      "directory_server_transaction_id": "1ccf8e46-c86e-42b1-9791-e54d4315b44b"
    }
  }
}
```

{% endtab %}

{% tab title="Validation Failed" %}

```json
{
  "status": "success",
  "message": "Validation failed, authentication unsuccessful",
  "data": {
    "transaction_info": {
      "type": "validate_result_response",
      "reference_code": "02ea9573-3ef1-450c-8a46-e459cb63d678",
      "request_id": "7513798812266365904806",
      "status": "Authentication_failed",
      "created_at": "2025-07-01T14:24:41Z"
    },
    "card": {
      "bin": "520000",
      "type": "MASTERCARD"
    },
    "consumer_auth_info": {
      "eci_raw": "00",
      "token": "AxjxbwSTl1Ln0fGouuelAk9+ZWihgKojhqBQ+hk0ky9GMjmDoBcAz1jA",
      "pares_status": "N",
      "acs_transaction_id": "406d1307-d60b-49fe-8d39-ca48514b66f0",
      "specificationVersion": "2.1.0",
      "tree_dss_server_transaction_id": "1ac7334c-38aa-4a54-99c0-08c214d8d690",
      "directory_server_transaction_id": "1ccf8e46-c86e-42b1-9791-e54d4315b44b"
    }
  }
}
```

{% endtab %}
{% endtabs %}

### Response Fields

#### transaction\_info

<table><thead><tr><th width="166.07421875">Field</th><th width="433.7265625">Description</th></tr></thead><tbody><tr><td><code>Type</code></td><td>"validate_result_response"</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" or "Authentication_failed"</td></tr><tr><td><code>Created At</code></td><td>ISO 8601 timestamp of validation</td></tr></tbody></table>

#### card

| Field  | Description                                 |
| ------ | ------------------------------------------- |
| `bin`  | Bank Identification Number (first 6 digits) |
| `type` | Card network (VISA, MASTERCARD, AMEX)       |

#### consumer\_auth\_info

**Success Response Fields**

| Field                             | Description                                                               |
| --------------------------------- | ------------------------------------------------------------------------- |
| `eci_raw`                         | Electronic Commerce Indicator (01/02 for Mastercard, 05/06 for VISA/AMEX) |
| `token`                           | Final authentication token                                                |
| `pares_status`                    | Y=Successfully authenticated                                              |
| `acs_transaction_id`              | Access Control Server transaction ID                                      |
| `specificationVersion`            | 3D Secure version used                                                    |
| `tree_dss_server_transaction_id`  | 3DS Server transaction ID                                                 |
| `directory_server_transaction_id` | Directory Server transaction ID                                           |

**Mastercard Specific Fields**

| Field                       | Description                                                              |
| --------------------------- | ------------------------------------------------------------------------ |
| `ucaf_authentication_data`  | Universal Cardholder Authentication Field - use in payment authorization |
| `ucaf_collection_indicator` | Indicator for UCAF collection method                                     |

**VISA/AMEX Specific Fields**

| Field Name | Description                                                                 |
| ---------- | --------------------------------------------------------------------------- |
| `eci`      | Electronic Commerce Indicator (same as `eci_raw`)                           |
| `cavv`     | Cardholder Authentication Verification Value - use in payment authorization |
| `xid`      | Transaction identifier                                                      |

**Failed Response Fields**

<table><thead><tr><th width="332.79296875">Field Name</th><th>Description</th></tr></thead><tbody><tr><td><code>eci_raw</code></td><td>Failure ECI code (00 for Mastercard, 07 for VISA/AMEX)</td></tr><tr><td><code>pares_status</code></td><td>N=Authentication failed</td></tr><tr><td><code>acs_transaction_id</code></td><td>Access Control Server transaction ID</td></tr><tr><td><code>specificationVersion</code></td><td>3D Secure version used</td></tr><tr><td><code>tree_dss_server_transaction_id</code></td><td>3DS Server transaction ID</td></tr><tr><td><code>directory_server_transaction_id</code></td><td>Directory Server</td></tr></tbody></table>

### Payment Authorization Data

#### Fields to Include in Payment Request

**For Mastercard**

```json
{
  "eci": "02",
  "ucaf_authentication_data": "AAIBBYNoEwAAACcKhAJkdQAAAAA=",
  "ucaf_collection_indicator": "2",
  "acs_transaction_id": "406d1307-d60b-49fe-8d39-ca48514b66f0"
}
```

**For VISA/AMEX**

```json
{
  "eci": "05",
  "cavv": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
  "xid": "AJkBBkhgQQAAAE4gSEJydQAAAAA=",
  "acs_transaction_id": "10373298-d099-415a-822b-37ae11d22d92"
}
```

### Usage Example

#### cURL

```json
curl --location 'https://api.firstoken.co/v1/risk/authentication/validate' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>' \
--data-raw '{
    "transaction_info": {
        "type": "validate_result",
        "reference_code": "123456789"
    },
    "card": {
        "number": "5200000000001096",
        "expiration_date": "01/2028"
    },
    "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": {
        "transaction_id": "DKjne4MBXRSsa1fryRE0"
    }
}'
```