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": "accept@gmsectec.com",
        "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

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

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

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": "accept@gmsectec.com",
        "postal_code": "94105"
    },
    "authentication": {
        "transaction_id": "DKjne4MBXRSsa1fryRE0"
    }
}'

PreviousCheck enroll NextFirstoken Captures Hosted Iframe

Last updated 1 day ago

Was this helpful?