Refunds

You can repay your customer for a previous transaction in part or fully by initiating a refund and listening to notifications.

Getting started

Sometimes, a customer makes a request for their money after a successful transaction. Other times, an order cannot be fulfilled after payment has been made. In either case, you need to consider if you should initiate a:

Partial refund or,
Full refund

Our Refund^API endpoints allow you to repay your customers in part or fully. You simply initiate a refund request and we keep you updated on the status of the refund.

Create a refund

To initiate a refund, you make a POST request to the Create Refund^API and pass the transaction ID or reference in the transaction field. If an amount isn't passed, we handle the request as a full refund.

If you want to do a partial refund, you pass an amount parameter with the amount to refund. The refund amount must not be more than the original transaction amount.

Show Response

1curl https://api.paystack.co/refund
2  -H 'authorization: Bearer YOUR_SECRET_KEY'
3  -H 'cache-control: no-cache'
4  -H 'content-type: application/json'
5  -d '{ "transaction":"qufywna9w9a5d8v", "amount":"10000" }
6  -X POST
7

1{
2  "status": true,
3  "message": "Refund has been queued for processing",
4  "data": {
5    "transaction": {
6      "id": 1004723697,
7      "domain": "live",
8      "reference": "T685312322670591",
9      "amount": 10000,
10      "paid_at": "2021-08-20T18:34:11.000Z",
11      "channel": "apple_pay",
12      "currency": "NGN",
13      "authorization": {
14        "exp_month": null,
15        "exp_year": null,
16        "account_name": null
17      },
18      "customer": {
19        "international_format_phone": null
20      },
21      "plan": {},
22      "subaccount": {
23        "currency": null
24      },
25      "split": {},
26      "order_id": null,
27      "paidAt": "2021-08-20T18:34:11.000Z",
28      "pos_transaction_data": null,
29      "source": null,
30      "fees_breakdown": null
31    },
32    "integration": 412829,
33    "deducted_amount": 0,
34    "channel": null,
35    "merchant_note": "Refund for transaction T685312322670591 by [email protected]",
36    "customer_note": "Refund for transaction T685312322670591",
37    "status": "pending",
38    "refunded_by": "[email protected]",
39    "expected_at": "2021-12-16T09:21:17.016Z",
40    "currency": "NGN",
41    "domain": "live",
42    "amount": 10000,
43    "fully_deducted": false,
44    "id": 3018284,
45    "createdAt": "2021-12-07T09:21:17.122Z",
46    "updatedAt": "2021-12-07T09:21:17.122Z"
47  }
48}

The refund amount must not be more than the original transaction amount.

List Refunds

To pull a list of your refunds, you can use the List Refunds^API to fetch all your refunds.

Show Response

1curl https://api.paystack.co/refund 
2-H 'authorization: Bearer YOUR_SECRET_KEY'
3-H 'cache-control: no-cache'
4-H 'content-type: application/json' 
5-X GET

1{
2  "status": true,
3  "message": "Refunds retrieved",
4  "data": [
5    {
6      "integration": 428626,
7      "transaction": 627178582,
8      "dispute": null,
9      "settlement": null,
10      "id": 747680,
11      "domain": "test",
12      "currency": "NGN",
13      "amount": 10000,
14      "status": "processed",
15      "refunded_at": null,
16      "refunded_by": "[email protected]",
17      "customer_note": "Refund for transaction qufywna9w9a5d8v",
18      "merchant_note": "Refund for transaction qufywna9w9a5d8v by [email protected]",
19      "deducted_amount": 10000,
20      "fully_deducted": true,
21      "createdAt": "2020-05-19T11:12:17.000Z"
22    },
23    {
24      "integration": 428626,
25      "transaction": 640672957,
26      "dispute": null,
27      "settlement": null,
28      "id": 742609,
29      "domain": "test",
30      "currency": "NGN",
31      "amount": 20000,
32      "status": "processed",
33      "refunded_at": null,
34      "refunded_by": "[email protected]",
35      "customer_note": "blah blah",
36      "merchant_note": "yada yada",
37      "deducted_amount": 20000,
38      "fully_deducted": true,
39      "createdAt": "2020-04-30T10:43:47.000Z"
40    }
41  ],
42  "meta": {
43    "total": 2,
44    "skipped": 0,
45    "perPage": 50,
46    "page": 1,
47    "pageCount": 1
48  }
49}

Refund status

During the lifecycle of a refund, its status changes based on the actions performed by the refund processor. When the status of a refund changes, the status of the associated transaction follows suit.

The table below shows the relationship between the status of a refund and its associated transaction:

Status	Description	Transaction Status
Pending	Refund initiated, waiting for response from the processor	Reversal Pending
Processing	Refund has been received by the processor.	Reversal Pending
Failed	Refund cannot be processed. Your account is credited with refund amount.	Success
Processed	Refund has successfully been processed by the processor.	Reversed

When a refund is marked as processed, it may still take up to 10 business days for customers to receive their funds.

Listen to notifications

In order to receive notifications, you need to implement a webhook URL and set the webhook URL in your Paystack dashboard.

We send different events based on the state of a refund. You can listen to the following events to stay updated on the state of a customer's refund:

Event	Description
refund.pending	This is sent when a refund is initiated and we are waiting for a response from the processor.
refund.processing	This is sent when the refund has been received by the processor.
refund.failed	This is sent when a refund cannot be processed. Your account is credited with the refund amount.
refund.processed	This is sent when the refund has been successfully processed by the processor.

Refund Pending
Refund Processing
Refund Processed
Refund Failed

1{
2  "event": "refund.pending",
3  "data": {
4    "status": "pending",
5    "transaction_reference": "tvunjbbd_412829_4b18075d_c7had",
6    "refund_reference": null,
7    "amount": "10000",
8    "currency": "NGN",
9    "processor": "instant-transfer",
10    "customer": {
11      "first_name": "Drew",
12      "last_name": "Berry",
13      "email": "[email protected]"
14    },
15    "integration": 412829,
16    "domain": "live"
17  }
18}

Refunds

In a nutshell

Getting started

Create a refund

Maximum refund amount

List Refunds

Refund status

Processed Refunds

Listen to notifications

Receiving Notifications