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

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 test@me.com",
36    "customer_note": "Refund for transaction T685312322670591",
37    "status": "pending",
38    "refunded_by": "test@me.com",
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": "jen@smith.com",
17      "customer_note": "Refund for transaction qufywna9w9a5d8v",
18      "merchant_note": "Refund for transaction qufywna9w9a5d8v by jen@smith.com",
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": "jen@smith.com",
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": "demo@email.com"
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