Refund
A collection of endpoints for creating and managing transaction reimbursement
Copy link List Refunds
List previously created refunds
Query Parameters
Number of records to fetch per page
The section to retrieve
The start date
The end date
Response
200Refund List response
6 object properties
GET
/refundcurl https://api.paystack.co/refund \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.refund.list({
perPage: 10,
page: 100
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.refund.list({
per_page: 10,
page: 100
})
puts response.dataResponse
{
"status": true,
"message": "Refunds retrieved",
"data": [
{
"id": 1,
"integration": 100982,
"domain": "live",
"transaction": 1641,
"dispute": 20,
"amount": 500000,
"deducted_amount": 500000,
"currency": "NGN",
"channel": "migs",
"fully_deducted": 1,
"refunded_by": "[email protected]",
"refunded_at": "2018-01-12T10:54:47.000Z",
"expected_at": "2017-10-01T21:10:59.000Z",
"settlement": null,
"customer_note": "xxx",
"merchant_note": "xxx",
"created_at": "2017-09-24T21:10:59.000Z",
"updated_at": "2018-01-18T11:59:56.000Z",
"status": "processed"
},
{
"id": 2,
"integration": 100982,
"domain": "test",
"transaction": 323896,
"dispute": 45,
"amount": 500000,
"deducted_amount": null,
"currency": "NGN",
"channel": "migs",
"fully_deducted": null,
"refunded_by": "[email protected]",
"refunded_at": "2017-09-24T21:11:53.000Z",
"expected_at": "2017-10-01T21:11:53.000Z",
"settlement": null,
"customer_note": "xxx",
"merchant_note": "xxx",
"created_at": "2017-09-24T21:11:53.000Z",
"updated_at": "2017-09-24T21:11:53.000Z",
"status": "pending"
}
]
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Create Refund
Initiate a refund for a previously completed transaction
Request Body
The reference of a previosuly completed transaction
Amount to be refunded to the customer. It cannot be more than the original transaction amount
Three-letter ISO currency
EnumGHSKESNGNUSDZAR
Customer reason
Merchant reason
Response
200Refund Create response
16 object properties
17 object properties
3 object properties
1 object property
1 object property
POST
/refundcurl https://api.paystack.co/refund \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"transaction": "mpkr39h74k"
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.refund.create({
transaction: "mpkr39h74k"
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.refund.create({
transaction: "mpkr39h74k"
})
puts response.dataResponse
{
"status": true,
"message": "Refund has been queued for processing",
"data": {
"transaction": {
"id": 1004723697,
"domain": "live",
"reference": "T685312322670591",
"amount": 10000,
"paid_at": "2021-08-20T18:34:11.000Z",
"channel": "apple_pay",
"currency": "NGN",
"authorization": {
"exp_month": null,
"exp_year": null,
"account_name": null
},
"customer": {
"international_format_phone": null
},
"plan": {},
"subaccount": {
"currency": null
},
"split": {},
"order_id": null,
"paidAt": "2021-08-20T18:34:11.000Z",
"pos_transaction_data": null,
"source": null,
"fees_breakdown": null
},
"integration": 412829,
"deducted_amount": 0,
"channel": null,
"merchant_note": "Refund for transaction T685312322670591 by [email protected]",
"customer_note": "Refund for transaction T685312322670591",
"status": "pending",
"refunded_by": "[email protected]",
"expected_at": "2021-12-16T09:21:17.016Z",
"currency": "NGN",
"domain": "live",
"amount": 10000,
"fully_deducted": false,
"id": 3018284,
"reference": "my-refund-001",
"createdAt": "2021-12-07T09:21:17.122Z",
"updatedAt": "2021-12-07T09:21:17.122Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}Copy link Retry Refund
Retry a refund with a `needs-attention` status by providing the bank account details of a customer.
Path Parameters
The identifier of the refund
Request Body
An object that contains the customer’s account details for refund
3 object properties
The currency of the customer's bank account. It should be the same as the currency the payment was made
The customer's account number
The ID representing the customer's bank. You can get the list of bank IDs by calling the List Banks endpoint.
Response
200Refund Create response
23 object properties
POST
/refund/retry_with_customer_details/{id}curl https://api.paystack.co/refund/retry_with_customer_details/15581137 \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Content-Type: application/json" \
-d '{
"refund_account_details": {}
}' \
-X POSTimport { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.refund.retry("15581137", {
refund_account_details: {}
});
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.refund.retry("15581137", {
refund_account_details: {}
})
puts response.dataResponse
{
"status": true,
"message": "Refund retried and has been queued for processing",
"data": {
"integration": 123456,
"transaction": 3298598423,
"dispute": null,
"settlement": null,
"id": 1234567,
"domain": "live",
"currency": "NGN",
"amount": 20000,
"status": "processing",
"refunded_at": null,
"expected_at": "2025-10-13T16:02:18.000Z",
"channel": "isw_3ds",
"refunded_by": "[email protected]",
"customer_note": "Refund for transaction T708775813895475",
"merchant_note": "Refund for transaction T708775813895475 by [email protected]",
"deducted_amount": 20000,
"fully_deducted": true,
"bank_reference": null,
"reason": "PROCESSING",
"customer": null,
"initiated_by": "[email protected]",
"reversed_at": null,
"session_id": null
}
}{
"status": false,
"message": "Invalid Refund state, refund status should be \"needs-attention\"",
"meta": {
"nextStep": "Ensure that the value(s) you're passing are valid."
},
"type": "validation_error",
"code": "invalid_params"
}Copy link Fetch Refund
Get a previously created refund
Path Parameters
The identifier of the refund
Response
200Refund Fetch response
26 object properties
9 object properties
GET
/refund/{id}curl https://api.paystack.co/refund/15581137 \
-H "Authorization: Bearer YOUR_SECRET_KEY"import { Paystack } from "@paystack/paystack-sdk";
const paystack = new Paystack({ secretKey: process.env.PAYSTACK_SECRET_KEY! });
const response = await paystack.refund.fetch("15581137");
console.log(response.data);require "paystack"
paystack = Paystack::Client.new(ENV.fetch("PAYSTACK_SECRET_KEY"))
response = paystack.refund.fetch("15581137")
puts response.dataResponse
{
"status": true,
"message": "Refund retrieved",
"data": {
"integration": 100982,
"transaction": 1641,
"dispute": null,
"settlement": null,
"domain": "live",
"amount": 500000,
"deducted_amount": 500000,
"fully_deducted": true,
"currency": "NGN",
"channel": "migs",
"status": "processed",
"refunded_by": "[email protected]",
"refunded_at": "2018-01-12T10:54:47.000Z",
"expected_at": "2017-10-01T21:10:59.000Z",
"customer_note": "xxx",
"merchant_note": "xxx",
"id": 1,
"createdAt": "2017-09-24T21:10:59.000Z",
"updatedAt": "2018-01-18T11:59:56.000Z"
}
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}{
"status": false,
"message": "An error occurred",
"meta": {
"nextStep": "string"
},
"type": "string",
"code": "validation_error",
"errorCodeMappingNotFound": true
}