> 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/setup.md).

# Setup

### Endpoint Details

**Method:** `POST`\
**URL:** <mark style="color:purple;">`/v1/risk/authentication/setup`</mark>\
**Purpose:** Initialize authentication and obtain secure communication tokens

### Headers

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

### Request Body

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

### Parameters

<table><thead><tr><th width="309.68359375">Field</th><th width="83.36328125">Type</th><th width="89.046875">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 "setup"</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.number</code></td><td>string</td><td>Yes</td><td>Card number (token or plain number)</td></tr><tr><td><code>card.expiration_date</code></td><td>string</td><td>Yes</td><td>Card expiration date (tokenized or MM/YY format)</td></tr></tbody></table>

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

{% tabs %}
{% tab title="Success Response" %}

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

{% endtab %}

{% tab title="Error Response" %}

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

{% endtab %}

{% tab title="System Error Response" %}

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

{% endtab %}
{% endtabs %}

### Response Fields

#### transaction\_info&#x20;

<table><thead><tr><th width="274.5078125">Field</th><th width="368.41796875">Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>Always "setup_auth_response"</td></tr><tr><td><code>transactiod_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>"Completed" for success, "Expired_card" for card errors</td></tr><tr><td><code>created_at</code></td><td>ISO 8601 timestamp of creation</td></tr></tbody></table>

#### consumer\_auth\_info

<table><thead><tr><th width="274.5078125">Field</th><th width="368.41796875">Description</th></tr></thead><tbody><tr><td><code>access_token</code></td><td>JWT token for secure communication</td></tr><tr><td><code>device_data_collection_url</code></td><td>URL for Cardinal device data collection</td></tr><tr><td><code>reference_id</code></td><td>Reference ID for the authentication session</td></tr><tr><td><code>token</code></td><td>Token to be used in the check enrollment step</td></tr></tbody></table>

#### error\_info (when applicable)

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

### Usage Example

#### cURL

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