Validate

Validates the authentication results after the user completes the 3D Secure challenge.

Endpoint Details

Method: POST URL: /v1/risk/authentication/validate 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

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

Request Body

{
    "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": "[e-mail]",
        "postal_code": "94105"
    },
    "authentication": {
        "transaction_id": "DKjne4MBXRSsa1fryRE0"
    }
}

Parameters

Field	Type	Required	Description
transaction_info.type	string	Yes	Must be "validate_result".
transaction_info.reference_code	string	Yes	Original transaction reference code.
card	object	Yes	Same card information as check_enroll.
order_info	object	Yes	Same order information as check_enroll.
bill_to	object	Yes	Same billing information as check_enroll.
authentication.transaction_id	string	Yes	Authentication transaction ID from check

Critical Parameter

authentication.transaction_id

This field must be the exact value from:

consumer_auth_info.authentication_transaction_id

From the Check Enrollment response.

Example: If Check Enrollment returned:

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

Then use in Validate:

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

Validation Successful

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

Validation Failed

Response Fields

transaction_info

Field	Description
Type	"validate_result_response"
Reference Code	Your original reference code
Request ID	Unique request identifier
Status	"Authentication_successful" or "Authentication_failed"
Created At	ISO 8601 timestamp of validation

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

Field Name	Description
eci_raw	Failure ECI code (00 for Mastercard, 07 for VISA/AMEX)
pares_status	N=Authentication failed
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

Payment Authorization Data

Fields to Include in Payment Request

For Mastercard

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

For VISA/AMEX

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

Usage Example

cURL

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": "[e-mail]",
        "postal_code": "94105"
    },
    "authentication": {
        "transaction_id": "DKjne4MBXRSsa1fryRE0"
    }
}'