Refund

A collection of endpoints for creating and managing transaction reimbursement

Copy link List Refunds

List previously created refunds

Query Parameters

perPageinteger
Number of records to fetch per page
pageinteger
The section to retrieve
fromstring
The start date
tostring
The end date

Response

200Refund List response
statusrequiredboolean
messagerequiredstring
datarequiredarray[object]
metarequiredobject
6 object properties
totalrequiredinteger
skippedrequiredinteger
perPagerequiredstring
pagerequiredinteger
pageCountrequiredinteger
failedRefundCountrequiredinteger
GET/refund
curl 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.data
Response
{
  "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

transactionrequiredstring
The reference of a previosuly completed transaction
amountinteger
Amount to be refunded to the customer. It cannot be more than the original transaction amount
currencystring
Three-letter ISO currency
EnumGHSKESNGNUSDZAR
customer_notestring
Customer reason
merchant_notestring
Merchant reason

Response

200Refund Create response
statusrequiredboolean
messagerequiredstring
datarequiredobject
16 object properties
transactionrequiredobject
17 object properties
idrequiredinteger
domainrequiredstring
referencerequiredstring
amountrequiredinteger
paid_atrequiredstring
channelrequiredstring
currencyrequiredstring
authorizationrequiredobject
3 object properties
exp_monthrequiredstring
exp_yearrequiredstring
account_namerequiredstring
customerrequiredobject
1 object property
international_format_phonerequiredstring
planrequiredobject
subaccountrequiredobject
1 object property
currencyrequiredstring
splitrequiredobject
order_idrequiredstring
paidAtrequiredstring
pos_transaction_datarequiredstring
sourcerequiredstring
fees_breakdownrequiredstring
integrationrequiredinteger
deducted_amountrequiredinteger
channelrequiredstring
merchant_noterequiredstring
customer_noterequiredstring
statusrequiredstring
refunded_byrequiredstring
expected_atrequiredstring
currencyrequiredstring
domainrequiredstring
amountrequiredinteger
fully_deductedrequiredboolean
idrequiredinteger
createdAtrequiredstring
updatedAtrequiredstring
POST/refund
curl https://api.paystack.co/refund \
  -H "Authorization: Bearer YOUR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction": "mpkr39h74k"
  }' \
  -X POST
import { 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.data
Response
{
  "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

idrequiredinteger
The identifier of the refund

Request Body

refund_account_detailsrequiredobject
An object that contains the customer’s account details for refund
3 object properties
currencyrequiredstring
The currency of the customer's bank account. It should be the same as the currency the payment was made
account_numberrequiredstring
The customer's account number
bank_idrequiredstring
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
statusrequiredboolean
messagerequiredstring
datarequiredobject
23 object properties
integrationrequirednumber
transactionrequirednumber
disputerequiredobject
settlementrequiredobject
idrequirednumber
domainrequiredstring
currencyrequiredstring
amountrequirednumber
statusrequiredstring
refunded_atrequiredstring
expected_atrequiredstring
channelrequiredstring
refunded_byrequiredstring
customer_noterequiredstring
merchant_noterequiredstring
deducted_amountrequirednumber
fully_deductedrequiredboolean
bank_referencerequiredstring
reasonrequiredstring
customerrequiredobject
initiated_byrequiredstring
reversed_atrequiredstring
session_idrequiredstring
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 POST
import { 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.data
Response
{
  "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

idrequiredinteger
The identifier of the refund

Response

200Refund Fetch response
statusrequiredboolean
messagerequiredstring
datarequiredobject
26 object properties
integrationrequiredinteger
transactionrequiredinteger
disputerequiredstring
settlementrequiredstring
idrequiredinteger
domainrequiredstring
currencyrequiredstring
amountrequiredinteger
statusrequiredstring
refunded_atrequiredstring
refunded_byrequiredstring
customer_noterequiredstring
merchant_noterequiredstring
deducted_amountrequiredinteger
fully_deductedrequiredinteger
createdAtrequiredstring
bank_referencerequiredstring
transaction_referencerequiredstring
reasonrequiredstring
customerrequiredobject
9 object properties
idrequiredinteger
first_namerequiredstring
last_namerequiredstring
emailrequiredstring
customer_coderequiredstring
phonerequiredstring
metadatarequiredstring
risk_actionrequiredstring
international_format_phonerequiredstring
refund_typerequiredstring
transaction_amountrequiredinteger
initiated_byrequiredstring
refund_channelrequiredstring
session_idrequiredstring
collect_account_numberrequiredboolean
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.data
Response
{
  "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
}