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

# Transfers and settlements

> Move money between wallets, to other banks, or to your own account.

Every transfer needs `transfers:write` and an `Idempotency-Key`. The bank's ledger decides whether it may go ahead: funds, limits, whose wallet it is and closed-loop rules.

| | Feature | Answers |
| - | - | - |
| `POST /v1/transfers/internal` | `TRANSFERS_INTERNAL` | `200`, `completed` |
| `POST /v1/transfers/interbank` | `TRANSFERS_INTERBANK` | `202`, `queued` |
| `POST /v1/settlements` | `SETTLEMENTS` | `202`, `queued` |

## Between wallets

```bash theme={null}
curl https://$MESH_HOST/v1/transfers/internal \
  -H "X-Api-Key: $MESH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "source_account_number": "6037000001",
    "destination_account_number": "6037000022",
    "amount_minor": 500000,
    "narration": "Refund for order 77123"
  }'
```

Done when it answers.

## To another bank

**1. Find the bank code**

`GET /v1/banks` lists banks and their codes.

**2. Check the name**

`GET /v1/account-names?account_number=0123456789&bank_code=058` returns the name on the account. Show it before you send.

**3. Send**

```bash theme={null}
curl https://$MESH_HOST/v1/transfers/interbank \
  -H "X-Api-Key: $MESH_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "account_number": "6037000001",
    "amount_minor": 1500000,
    "beneficiary_bank_code": "058",
    "beneficiary_account_number": "0123456789",
    "beneficiary_account_name": "ADA OBI",
    "narration": "Supplier payment"
  }'
```

It answers `queued`: the amount, the charge and its VAT have left the wallet.

**4. Follow it**

`GET /v1/transfers/interbank/{transactionId}` moves through `processing` to `settled`, `failed` or `reversed`. You also receive `transfer.interbank.settled`, `.failed` or `.reversed`.

## To your own bank account

`POST /v1/settlements` moves money from your wallet to your business's account at the bank. Follow it with `GET /v1/settlements/{transactionId}` or the `settlement.*` webhooks.

## Rules

* **Payouts and settlements leave only from your business's own wallet** (`422`, code `86`).
* **Limits.** A business wallet sends at most ₦5,000,000 a transfer and ₦25,000,000 a day unless the bank set it its own (`422`, code `83`).
* **Customers' wallets.** Only a closed-loop business can move money out of its customers' wallets (`403`, code `82`), and that money can go only to its own wallets or its other customers (`422`, code `81`).
* **Not enough money** for the amount and its charges is `422` (code `80`); a restricted account, `422` (code `85`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.