Refunds API

Create and manage refunds for completed payments.

Base URL

http://localhost:8081

Create a Refund

POST/refunds

Request Body

{
  "payment_id": "pay_xyz789",
  "amount": 50000,
  "currency": "NGN",
  "reason": "requested_by_customer",
  "metadata": {
    "reason_note": "Customer returned item"
  }
}

Response

{
  "refund_id": "ref_abc789",
  "payment_id": "pay_xyz789",
  "amount": 50000,
  "currency": "NGN",
  "status": "Succeeded",
  "reason": "requested_by_customer",
  "created_at": "2026-07-26T11:00:00Z",
  "metadata": {
    "reason_note": "Customer returned item"
  }
}

Retrieve a Refund

GET/refunds/{refund_id}

curl -X GET http://localhost:8081/refunds/ref_abc789 \
  -H "api-key: test_api_key_xxxx"

List Refunds

GET/refunds

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results (default 20, max 100)
`offset`	integer	Number of results to skip
`payment_id`	string	Filter refunds by payment ID
`status`	string	Filter by status: Succeeded, Failed, Pending
`created`	object	Date range filter

Refund Statuses

Status	Description
Pending	Refund initiated, awaiting connector confirmation
Succeeded	Refund completed by the connector
Failed	Refund failed at the connector
Cancelled	Refund was cancelled before processing