> ## 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 International Bank Account

> Link an international bank account for cross-border payouts and wire transfers.

## Overview

Link an international bank account to enable cross-border wire transfers and international payouts. This endpoint allows you to connect a customer's international bank account as a payout destination.

## Prerequisites

* An application token (obtained from creating a withdrawal widget or account widget)
* Valid access token

## Endpoint

* **POST** `{{LIQUIDITY_URL}}/v1/ext/application-token/:token/linked-accounts/:currency/link/international_bank/:step`
* Auth: Bearer `{{accessToken}}`

### Path Parameters

| Parameter  | Type   | Description                                  | Required |
| ---------- | ------ | -------------------------------------------- | -------- |
| `token`    | string | Application token from payout/account widget | Yes      |
| `currency` | string | Currency code (e.g., `USD`)                  | Yes      |
| `step`     | string | Usually `1`                                  | Yes      |

## Request

```bash theme={null}
curl -X POST "{{LIQUIDITY_URL}}/v1/ext/application-token/{{token}}/linked-accounts/USD/link/international_bank/1" \
  -H "Authorization: Bearer {{accessToken}}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "My UK Business Account",
    "data": {
      "firstName": "John",
      "lastName": "Doe",
      "name": "Quantum Works LLC",
      "accountNumber": "8991026399",
      "swiftOrBic": "031000053",
      "bankName": "ABC bank",
      "recipientAddress": "9401 San francisco",
      "recipientCity": "San francisco",
      "recipientState": "CA",
      "recipientPostalCode": "9401",
      "email": "timi@gradientfi.com",
      "recipientCountry": "NG",
      "recipientType": "personal",
      "nickName": "MayetopsC"
    }
  }'
```

### Request Body Fields

| Field                      | Type   | Description                                                                                 | Required |
| -------------------------- | ------ | ------------------------------------------------------------------------------------------- | -------- |
| `label`                    | string | Display name for the linked account                                                         | Yes      |
| `data.firstName`           | string | First name of recipient                                                                     | Yes      |
| `data.lastName`            | string | Last name of recipient                                                                      | Yes      |
| `data.name`                | string | Business/account name                                                                       | Yes      |
| `data.accountNumber`       | string | International bank account number                                                           | Yes      |
| `data.swiftOrBic`          | string | SWIFT/BIC code                                                                              | Yes      |
| `data.bankName`            | string | Name of the international bank                                                              | Yes      |
| `data.recipientAddress`    | string | Full address of the recipient                                                               | Yes      |
| `data.recipientCity`       | string | City of the recipient                                                                       | Yes      |
| `data.recipientState`      | string | State/region of the recipient                                                               | Yes      |
| `data.recipientPostalCode` | string | Postal code of the recipient                                                                | Yes      |
| `data.email`               | string | Email of the recipient                                                                      | Yes      |
| `data.recipientCountry`    | string | ISO country code (2 letters, e.g., `NG`)                                                    | Yes      |
| `data.recipientType`       | string | Recipient type: `personal` or `business`                                                    | Yes      |
| `data.nickName`            | string | Nickname for this linked account (e.g. "MayetopsC"). If omitted, top-level `label` is used. | No       |

## Response (200)

```json theme={null}
{
  "success": true,
  "message": "Account successfully linked!",
  "data": {
    "id": "6b7c509b-93f4-4b51-a8e4-61cabed5eea0"
  }
}
```

### Response Fields

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

## Notes

* Store the `id` from the response for use in withdrawal requests
* Provide accurate recipient address/country data for compliance
* SWIFT/BIC should match the destination bank
* International wire transfers may have higher fees and longer processing times
* The linked account can be used for withdrawals once successfully created