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.

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": "[e-mail]",
  "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:

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.

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=[e-mail]&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)