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

# Send and Track Bank Transfers via Paylink Disbursements

> Learn how to initialize disbursements to any bank account, verify transfer status, and manage your payout history using the Paylink Transfers API.

The Transfers (Disbursements) API lets you send funds directly from your Paylink merchant balance to any Nigerian bank account. Use it for merchant payouts, vendor payments, customer refund alternatives, or any flow that requires moving money out of your balance.

<Warning>
  Attempting a transfer when your merchant balance is insufficient returns a `409` error. Check your available balance before initializing large or bulk disbursements.
</Warning>

## Initialize a Transfer

Send a `POST` request to `/disbursements/initialize` from your server to instruct Paylink to transfer funds on your behalf.

```json Request theme={null}
{
  "customer_name": "Ada Lovelace",
  "customer_email": "ada@example.com",
  "reference": "payout_12345",
  "amount": 10000.00,
  "currency": "NGN",
  "destination_bank_code": "058",
  "destination_bank_account": "0123456789",
  "destination_bank_name": "Example Bank",
  "narration": "Merchant payout",
  "metadata": { "payout_id": "12345" },
  "webhook_url": "https://merchant.example.com/webhooks/transfers"
}
```

| Field                      | Required | Description                                                                       |
| -------------------------- | -------- | --------------------------------------------------------------------------------- |
| `customer_name`            | ✅        | Full name of the recipient as it appears on their bank account                    |
| `customer_email`           | ✅        | Email address of the recipient                                                    |
| `reference`                | ✅        | Your unique identifier for this transfer. Must be unique across all disbursements |
| `amount`                   | ✅        | Amount to transfer in the specified currency                                      |
| `currency`                 | ✅        | ISO currency code, e.g. `NGN`                                                     |
| `destination_bank_code`    | ✅        | Three-digit code of the recipient's bank                                          |
| `destination_bank_account` | ✅        | Recipient's bank account number                                                   |
| `destination_bank_name`    | ✅        | Human-readable name of the recipient's bank                                       |
| `narration`                | Optional | Description shown on the recipient's bank statement                               |
| `metadata`                 | Optional | Key-value pairs to attach to the disbursement for your own records                |
| `webhook_url`              | Optional | URL that receives async transfer status notifications                             |

<Tip>
  Use `POST /banks/resolve` to verify the account name against the account number and bank code **before** sending. This confirms the destination is correct and avoids misdirected transfers that are difficult to recover.
</Tip>

A successful initialization response confirms the transfer has been queued:

```json Response theme={null}
{
  "status": "processing",
  "message": "Transfer has been queued",
  "reference": "payout_12345"
}
```

<Note>
  Transfers are processed asynchronously. The `processing` status in the initialization response means the request has been accepted — it does not mean the funds have landed in the recipient's account yet.
</Note>

## Verify Transfer Status

Poll `GET /disbursements/verify/{reference}` to check the current state of a transfer:

```http Request theme={null}
GET /disbursements/verify/payout_12345
```

```json Response theme={null}
{
  "status": "success",
  "reference": "payout_12345",
  "amount": 10000.00,
  "currency": "NGN",
  "destination_bank_account": "0123456789",
  "destination_bank_name": "Example Bank",
  "narration": "Merchant payout",
  "completed_at": "2026-01-20T15:45:00Z"
}
```

### Transfer Statuses

| Status       | Meaning                                                       |
| ------------ | ------------------------------------------------------------- |
| `processing` | Transfer is queued or in flight                               |
| `success`    | Funds have been credited to the recipient's account           |
| `failed`     | Transfer could not be completed                               |
| `reversed`   | Transfer was initially successful but has since been reversed |
| `expired`    | Transfer was not processed within the allowed window          |

<Tip>
  Set a `webhook_url` when you initialize the transfer so Paylink can push a status update to your server the moment the outcome is known — without you needing to poll.
</Tip>

## Handle Async Completion

Because transfers are asynchronous, your integration should account for the delay between initialization and final settlement:

1. **Initialize** the transfer and store the `reference` in your database with a `processing` status.
2. **Listen** for the webhook event fired to your `webhook_url` when the status changes.
3. **Verify** the final status by calling `GET /disbursements/verify/{reference}` when you receive the webhook, before updating your records.
4. **Update** your internal state to `success`, `failed`, or `reversed` based on the verified response.

```json Webhook event payload (example) theme={null}
{
  "event_type": "disbursement_success",
  "status": "success",
  "message": "Transfer completed successfully",
  "event_id": "evt_def456uvw",
  "timestamp": "2026-01-20T15:45:00Z",
  "data": {
    "reference": "payout_12345",
    "amount": 10000.00,
    "currency": "NGN",
    "metadata": { "payout_id": "12345" }
  }
}
```

## View Transfer History

Retrieve a paginated list of all your disbursements at `GET /merchants/disbursements`:

```http Example request theme={null}
GET /merchants/disbursements?status=success&customer_email=ada@example.com&start_date=2026-01-01&end_date=2026-01-31&page=1&page_size=25
```

| Parameter        | Description                                          |
| ---------------- | ---------------------------------------------------- |
| `status`         | Filter by transfer status (e.g. `success`, `failed`) |
| `customer_email` | Filter by recipient email address                    |
| `start_date`     | Earliest transfer date (ISO 8601)                    |
| `end_date`       | Latest transfer date (ISO 8601)                      |
| `page`           | Page number (default `1`)                            |
| `page_size`      | Results per page (default `10`, max `100`)           |