Initialize and Track Refunds for Paylink Payments

Paylink lets you refund any successful payment, either in full or partially. Refunds are processed asynchronously — after you initialize a refund, poll the status endpoint or listen for a webhook event to confirm completion.

Initialize a Refund

Send a POST request to /refunds/initialize to start a refund:

Request

{
  "payment_reference": "order_12345",
  "refund_reference": "refund_12345",
  "currency": "NGN",
  "amount": 500.00,
  "reason": "Customer requested a partial refund",
  "account_number": "0123456789",
  "bank_code": "058"
}

Field	Required	Description
`payment_reference`	✅	Reference of the original payment to refund
`refund_reference`	✅	Your unique identifier for this refund request
`currency`	✅	Currency of the refund, e.g. `NGN`
`amount`	✅	Amount to refund. Must not exceed the original payment amount
`reason`	Optional	Short description of why the refund is being issued
`account_number`	Conditional	Destination bank account number. Required when the customer’s card cannot be credited directly
`bank_code`	Conditional	Three-digit bank code for the destination account. Required when `account_number` is provided

Full vs. Partial Refunds

The amount field controls whether a refund is full or partial:

Full refund — set amount to the exact amount of the original payment.
Partial refund — set amount to any value less than the original payment amount.

You can issue multiple partial refunds against a single payment as long as their total does not exceed the original charge.

account_number and bank_code may be required depending on the original payment method. If the customer paid by card and their card cannot be credited directly, you must provide a destination bank account.

A successful response confirms the refund has been queued:

Response

{
  "status": "processing",
  "message": "Refund has been queued for processing",
  "refund_reference": "refund_12345",
  "payment_reference": "order_12345"
}

Each refund_reference must be unique across all your refund requests. Submitting a duplicate refund_reference returns a 409 error. Generate a new reference for every refund attempt, even if you are retrying a failed one.

Track Refund Status

Get a Single Refund

Call GET /refunds/{refund_reference} to fetch the current status of a specific refund:

Request

GET /refunds/refund_12345

Response

{
  "refund_reference": "refund_12345",
  "payment_reference": "order_12345",
  "amount": 500.00,
  "currency": "NGN",
  "status": "success",
  "reason": "Customer requested a partial refund",
  "created_at": "2026-01-20T14:22:00Z"
}

Refund Statuses

Status	Meaning
`processing`	The refund has been queued and is being processed by the banking network
`success`	Funds have been returned to the customer
`failed`	The refund could not be completed. Contact support if this persists

Rather than polling repeatedly, set up a webhook listener to receive a notification when the refund status changes to success or failed.

List All Refunds for a Payment

To see every refund associated with a specific original payment, call GET /refunds/transactions/{payment_reference}:

Request

GET /refunds/transactions/order_12345

This is useful when a payment has received multiple partial refunds and you need to reconcile the total amount refunded.

Query Refund History

Retrieve a paginated list of all refunds across your merchant account at GET /merchants/refunds:

Example request

GET /merchants/refunds?status=processing&start_date=2026-01-01&end_date=2026-01-31&page=1&page_size=25

Parameter	Description
`status`	Filter by refund status: `processing`, `success`, or `failed`
`payment_reference`	Filter refunds tied to a specific original payment
`start_date`	Earliest refund date (ISO 8601)
`end_date`	Latest refund date (ISO 8601)
`page`	Page number (default `1`)
`page_size`	Results per page (default `10`, max `100`)

Get Refund Counts by Status

For a quick summary of your refund activity, call GET /refunds/count-by-status:

Request

GET /refunds/count-by-status

Response

{
  "processing": 4,
  "success": 118,
  "failed": 2
}

This endpoint is handy for dashboard widgets or monitoring alerts — for example, alerting your team when the failed count spikes unexpectedly.

Get Started

Core Concepts

Guides

Resources

Initialize and Track Refunds for Paylink Payments

Initialize a Refund

Full vs. Partial Refunds

Track Refund Status

Get a Single Refund

Refund Statuses

List All Refunds for a Payment

Query Refund History

Get Refund Counts by Status

​Initialize a Refund

​Full vs. Partial Refunds

​Track Refund Status

​Get a Single Refund

​Refund Statuses

​List All Refunds for a Payment

​Query Refund History

​Get Refund Counts by Status

Initialize a Refund

Full vs. Partial Refunds

Track Refund Status

Get a Single Refund

Refund Statuses

List All Refunds for a Payment

Query Refund History

Get Refund Counts by Status