Setup

Initializes the payer authentication process and obtains the necessary tokens for the 3D Secure flow.

Endpoint Details

Method: POST URL: /v1/risk/authentication/setup Purpose: Initialize authentication and obtain secure communication tokens

Headers

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

Request Body

{
  "transaction_info": {
    "type": "setup",
    "reference_code": "d47f5455-0282-46c7-b1fc-eaf7ac0d85bf"
  },
  "card": {
    "number": "4000000000002701",
    "expiration_date": "01/2027"
  }
}

Parameters

Field	Type	Required	Description
transaction_info.type	string	Yes	Must be "setup"
transaction_info.reference_code	string	Yes	Unique transaction reference code
card.number	string	Yes	Card number (token or plain number)
card.expiration_date	string	Yes	Card expiration date (tokenized or MM/YY format)

Card Information Formats

Card Number Formats

• Permanent Token: "{{token_id : detokenize}}" - For stored card tokens

• Temporal Token: "{{temp_token_id : transaction}}" - For one-time use tokens

• Plain Card Number: "4111111111111111" - Card number string

Expiration Date Formats

• Tokenized: "{{temp_token_id : transaction}}" - When using tokens

• Plain Format: "01/25" - MM/YY format

---

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

Success Response

{
    "status": "success",
    "message": "Payer authentication setup successful",
    "data": {
        "transaction_info": {
            "type": "setup_auth_response",
            "transaction_id": "0001751379579478732946",
            "reference_code": "123456789",
            "request_id": "7513795796496267604805",
            "status": "Completed",
            "created_at": "2025-07-01T14:19:39Z"
        },
        "consumer_auth_info": {
            "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
            "device_data_collection_url": "https://centinelapistag.cardinalcommerce.com/V1/Cruise/Collect",
            "reference_id": "21db503f-1eb5-4a77-81e8-1129c4106af3",
            "token": "AxixbwSTl1LdGx33S/NFAU9+ZWgkZAKH0MmkmXoxkcwdAJgAOBao"
        }
    }
}

Error Response

{
    "status": "success",
    "message": "Expired Card",
    "data": {
        "transaction_info": {
            "type": "setup_auth_response",
            "reference_code": "123456789",
            "request_id": "7513795523116864804807",
            "status": "Expired_card",
            "created_at": "2025-07-01T14:19:12Z"
        },
        "error_info": {
            "reason": "Expired_card",
            "message": "Decline - Expired card. You might also receive this if the expiration date you provided does not match the date the issuing bank has on file."
        }
    }
}

System Error Response

{
    "status_code": 401,
    "status": "fail",
    "description": "Unauthorized"
}

Response Fields

transaction_info

Field	Description
type	Always "setup_auth_response"
transactiod_id	Unique transaction identifier
reference_code	Your original reference code
request_id	Unique request identifier
status	"Completed" for success, "Expired_card" for card errors
created_at	ISO 8601 timestamp of creation

consumer_auth_info

Field	Description
access_token	JWT token for secure communication
device_data_collection_url	URL for Cardinal device data collection
reference_id	Reference ID for the authentication session
token	Token to be used in the check enrollment step

error_info (when applicable)

Field	Description
reason	Error code
message	Detailed error description

Usage Example

cURL

curl --location 'https://api.firstoken.co/v1/risk/authentication/setup' \
--header 'x-api-key: <YOUR_API_KEY>' \
--header 'Content-Type: application/json' \
--data '{
  "transaction_info": {
    "type": "setup",
    "reference_code": "123456789"
  },
  "card": {
    "number": "4111111111111111",
    "expiration_date": "01/25"
  }
}'

Next Steps

After a successful setup:

1. Implement Cardinal SDK: Use the device_data_collection_url to collect device data

2. Proceed to Check Enrollment: Use the reference_id and token in the next API call

3. Store Session Data: Keep the authentication tokens for the enrollment step