Initialize and Track Refunds for Paylink Payments

Learn how to initialize full or partial refunds, track refund status, query refund history, and handle async completion with Paylink.

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.