> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centryos.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Link Card Account

> Link a debit card (push-to-card) as a payout destination using an application token.

## Overview

Link a payout destination (debit card) for an entity using an application token. The token is passed in the URL; **no Bearer auth is required** for this endpoint.

**Typical flow:**

1. Obtain an application token (e.g. account-widget token).
2. Call this endpoint with the token, currency, option `CARD`, step (e.g. `1`), and the required body.
3. On success, use the returned `data.id` for payouts (e.g. [Withdraw to Linked Account](/guides/withdraw-to-linked-account)).

**Supported (USD):** CARD – Debit card (push-to-card).

## Endpoint

* **POST** `{{LIQUIDITY_URL}}/v1/ext/application-token/:token/linked-accounts/:currency/link/:option/:step`
* **Auth:** None (token is in the URL). Do not send `Authorization` header.
* **Headers:** `Content-Type: application/json` required.

### Path Parameters

| Parameter  | Type   | Required | Description                                    |
| ---------- | ------ | -------- | ---------------------------------------------- |
| `token`    | string | Yes      | Application token (e.g. account-widget token). |
| `currency` | string | Yes      | Currency. For this doc: `USD`.                 |
| `option`   | string | Yes      | Link type: `CARD`.                             |
| `step`     | string | Yes      | Step in the flow; typically `1`.               |

## Request Body

Every request must include:

| Field   | Type   | Required | Description                                              |
| ------- | ------ | -------- | -------------------------------------------------------- |
| `label` | string | Yes      | Nickname for this linked account (e.g. "My debit card"). |
| `data`  | object | Yes      | Payload for CARD; see below.                             |

### CARD – data fields

| Field                 | Type   | Required        | Description                                                                                 |
| --------------------- | ------ | --------------- | ------------------------------------------------------------------------------------------- |
| `name`                | string | Yes if business | Business name.                                                                              |
| `firstName`           | string | Yes if personal | Cardholder first name.                                                                      |
| `lastName`            | string | Yes if personal | Cardholder last name.                                                                       |
| `email`               | string | Yes             | Valid email.                                                                                |
| `cardNumber`          | string | Yes             | 16-digit card number.                                                                       |
| `cardExpirationDate`  | string | Yes             | Expiry in `YYYY-MM` (e.g. 2026-04).                                                         |
| `recipientAddress`    | string | Yes             | Street address.                                                                             |
| `recipientCity`       | string | Yes             | City.                                                                                       |
| `recipientState`      | string | Yes             | 2-letter state code.                                                                        |
| `recipientPostalCode` | string | Yes             | US ZIP.                                                                                     |
| `nickName`            | string | No              | Nickname for this linked account (e.g. "MayetopsC"). If omitted, top-level `label` is used. |

## Request Example

### Personal card

```bash theme={null}
curl -X POST "{{LIQUIDITY_URL}}/v1/ext/application-token/{{token}}/linked-accounts/USD/link/CARD/1" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My debit card",
    "data": {
      "recipientType": "personal",
      "firstName": "John",
      "lastName": "Smith",
      "email": "john.smith@example.com",
      "cardNumber": "5555555555554444",
      "cardExpirationDate": "2026-04",
      "recipientAddress": "789 Oak St",
      "recipientCity": "Los Angeles",
      "recipientState": "CA",
      "recipientPostalCode": "90001",
      "nickName": "MayetopsC"
    }
  }'
```

## Response

### Success (200)

```json theme={null}
{
  "success": true,
  "message": "Account successfully linked!",
  "data": {
    "id": "845a276a-3c5a-45ff-9aa9-6b266a77f92a"
  }
}
```

| Field     | Type   | Description                                          |
| --------- | ------ | ---------------------------------------------------- |
| `success` | bool   | `true` on success                                    |
| `message` | string | `"Account successfully linked!"`                     |
| `data.id` | string | Linked account ID — use this for withdrawal requests |

* Use `data.id` when calling the [withdrawal endpoint](/guides/withdraw-to-linked-account):\
  `POST /v1/ext/linked-accounts/{currency}/{linkedAccountId}/withdrawal`

### Error (4xx / 5xx)

```json theme={null}
{
  "success": false,
  "message": "<error detail or validation messages>",
  "fatal": true
}
```

### Typical Error Cases

| Situation             | HTTP | Notes                                                                 |
| --------------------- | ---- | --------------------------------------------------------------------- |
| Invalid/expired token | 400  | "Invalid or expired application token".                               |
| Wrong token type      | 400  | Token must be account-widget type.                                    |
| Validation error      | 400  | Missing/invalid fields.                                               |
| Personal account      | 400  | `firstName` and `lastName` required when `recipientType` is personal. |
| Business account      | 400  | `name` required when `recipientType` is business.                     |
| card number           | 400  | Exactly 16 digits.                                                    |
| expiration            | 400  | Format `YYYY-MM`.                                                     |
| Duplicate nickname    | 400  | "Nickname already exists, please choose a different nickname".        |
| No platform account   | 400  | No wallet found for entity/currency.                                  |
| Processing error      | 500  | Message may reflect processing or server error.                       |

## Validation Summary

* **label** – Required, any non-empty string.
* **option** – Required, `CARD` (must match path).
* **data** – Required; structure as above.
* **recipientType** – Required; `personal` or `business`.
* **cardNumber** – Exactly 16 digits.
* **cardExpirationDate** – `YYYY-MM`.

## Notes for Integrators

* Obtain a valid application token (account-widget type) before calling this endpoint.
* Use the returned `data.id` when calling the [external withdrawal API](/guides/withdraw-to-linked-account).
* For CARD, payouts are push-to-card regardless of routing.
* Do not send card number in logs or client-side storage; treat as sensitive.
* Same endpoint is used for non-external path with token in URL; external path is `POST /v1/ext/application-token/{token}/linked-accounts/{currency}/link/{option}/{step}`.