> For the complete documentation index, see [llms.txt](https://docs.ezeebit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ezeebit.com/customer-accounts/customer-account-transfer.md).

# Customer Account Transfer

Move USDT between your crypto wallet and a customer account, in either direction.

**Live:**

<mark style="color:green;">`POST`</mark> [<mark style="color:blue;">https://api.ezeebit.com/open/api/v1/customerAccount/transfer</mark>](https://api.ezeebit.com/open/api/v1/customerAccount/transfer)

**UAT:**

<mark style="color:green;">`POST`</mark> [<mark style="color:blue;">https://uat-api.ezeebit.com/open/api/v1/customerAccount/transfer</mark>](https://uat-api.ezeebit.com/open/api/v1/customerAccount/transfer)

## Headers

| Name                   | Type   | Required | Value                          |
| ---------------------- | ------ | -------- | ------------------------------ |
| Content-Type           | string | Y        | application/json               |
| Ezeebit-Timestamp      | long   | Y        | Unix timestamp in milliseconds |
| Ezeebit-Nonce          | string | Y        | 32 characters                  |
| Ezeebit-Certificate-SN | string | Y        | API key issued by Ezeebit Pay  |
| Ezeebit-Signature      | string | Y        | Uppercase SHA512 signature     |

## Request Body

{% tabs %}
{% tab title="To a customer" %}

```json
{
  "from": { "type": "MERCHANT" },
  "to": { "type": "CUSTOMER", "customerAccountId": "cust-1001" },
  "unit": "USDT",
  "amount": 50.00,
  "idempotencyKey": "6f1e2d3c-4b5a-4978-8a1b-2c3d4e5f6a7b"
}
```

{% endtab %}

{% tab title="From a customer" %}

```json
{
  "from": { "type": "CUSTOMER", "customerAccountId": "cust-1001" },
  "to": { "type": "MERCHANT" },
  "unit": "USDT",
  "amount": 20.00,
  "idempotencyKey": "9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d"
}
```

{% endtab %}
{% endtabs %}

## Form data

| Parameter      | Type    | Required | Description                                                                                                                                            |
| -------------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| from           | object  | Yes      | The sending side. `{"type": "MERCHANT"}` is your own USDT wallet. `{"type": "CUSTOMER", "customerAccountId": "..."}` is one of your customer accounts. |
| to             | object  | Yes      | The receiving side, in the same shape.                                                                                                                 |
| unit           | string  | Yes      | `USDT`.                                                                                                                                                |
| amount         | decimal | Yes      | Amount to move. Greater than `0`.                                                                                                                      |
| idempotencyKey | string  | No       | Retry key, at most **128 characters**. Retrying with the same key returns the original transfer and moves nothing.                                     |

One side must be `MERCHANT` and the other `CUSTOMER`. Transfers between two customer accounts aren't supported. Send `customerAccountId` on the `CUSTOMER` side only.

A transfer is a book entry: it completes at once, nothing goes on chain, and there's no fee. Both sides get a `TRANSFER` entry, in your [Wallet Transactions](https://docs.ezeebit.com/wallets-and-withdrawal/wallet-transactions.md) and in the [Customer Account Ledger](https://docs.ezeebit.com/customer-accounts/customer-account-ledger.md). Transfers don't send a [Wallet Webhook](https://docs.ezeebit.com/wallets-and-withdrawal/wallet-webhook.md).

A retry with the same `idempotencyKey` returns the original `transferId` and `amount`, with each side's current balance as `balanceAfter`.

## Response

<table><thead><tr><th width="190">Status</th><th>Description</th></tr></thead><tbody><tr><td>200</td><td>Transfer completed</td></tr><tr><td>10108</td><td>Customer account is frozen</td></tr><tr><td>10109</td><td>The sending side doesn't have enough balance</td></tr><tr><td>10110</td><td>Transfers between two customer accounts aren't supported</td></tr><tr><td>10111</td><td>A balance changed during the transfer. Retry it</td></tr><tr><td>10121</td><td>Customer account not found</td></tr><tr><td>10123</td><td>A side's <code>type</code> is missing or invalid, or <code>customerAccountId</code> is missing on a <code>CUSTOMER</code> side or sent on the <code>MERCHANT</code> side</td></tr><tr><td>10124</td><td><code>from</code> and <code>to</code> are the same wallet</td></tr><tr><td>10125</td><td><code>unit</code> is not <code>USDT</code></td></tr><tr><td>10126</td><td><code>amount</code> is missing, or not greater than <code>0</code></td></tr></tbody></table>

### Response fields

<table><thead><tr><th width="170">Field</th><th width="90">Type</th><th>Description</th></tr></thead><tbody><tr><td>transferId</td><td>string</td><td>Transfer ID. It is the <code>reference</code> on the customer account's ledger entry</td></tr><tr><td>unit</td><td>string</td><td><code>USDT</code></td></tr><tr><td>amount</td><td>string</td><td>Amount moved</td></tr><tr><td>createdAt</td><td>long</td><td>Epoch milliseconds</td></tr><tr><td>from, to</td><td>object</td><td>Each side's <code>type</code>, <code>customerAccountId</code> (<code>null</code> on the <code>MERCHANT</code> side) and <code>balanceAfter</code></td></tr></tbody></table>

{% tabs %}
{% tab title="200" %}

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "transferId": "0b7d4c2e-91a3-4f6e-b8d2-5c1a9e7f3d40",
    "unit": "USDT",
    "amount": "50.00",
    "createdAt": 1761811200000,
    "from": {
      "type": "MERCHANT",
      "customerAccountId": null,
      "balanceAfter": "3350.00000000"
    },
    "to": {
      "type": "CUSTOMER",
      "customerAccountId": "cust-1001",
      "balanceAfter": "300.00000000"
    }
  }
}
```

{% endtab %}

{% tab title="10109" %}

```json
{
  "code": 10109,
  "msg": "Insufficient balance to complete this transfer",
  "data": null
}
```

{% endtab %}
{% endtabs %}
