Send and Track Bank Transfers via Paylink Disbursements

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.

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

Initialize a Transfer

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

Request

{
  "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

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.

A successful initialization response confirms the transfer has been queued:

Response

{
  "status": "processing",
  "message": "Transfer has been queued",
  "reference": "payout_12345"
}

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.

Verify Transfer Status

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

Request

GET /disbursements/verify/payout_12345

Response

{
  "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

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.

Handle Async Completion

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

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

Webhook event payload (example)

{
  "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:

Example request

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`)

Get Started

Core Concepts

Guides

Resources

Send and Track Bank Transfers via Paylink Disbursements

Initialize a Transfer

Verify Transfer Status

Transfer Statuses

Handle Async Completion

View Transfer History

​Initialize a Transfer

​Verify Transfer Status

​Transfer Statuses

​Handle Async Completion

​View Transfer History

Initialize a Transfer

Verify Transfer Status

Transfer Statuses

Handle Async Completion

View Transfer History