Refunds

The Refunds API allows you create and manage transaction refunds.

Create Refund

Initiate a refund on your integration

Headers
authorization String	Set value to `Bearer SECRET_KEY`
content-type String	Set value to `application/json`

Body Parameters
Show optional parameters
transaction String	Transaction reference or id
amount Integer	Amount ( in kobo if currency is `NGN`, pesewas, if currency is `GHS`, and cents, if currency is `ZAR` ) to be refunded to the customer. Amount is optional(defaults to original transaction amount) and cannot be more than the original transaction amount.
currency String	Three-letter ISO currency. Allowed values are: NGN, GHS, ZAR or USD
customer_note String	Customer reason
merchant_note String	Merchant reason

1curl https://api.paystack.co/refund
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-H "Content-Type: application/json"
4-d '{ "transaction": 1641 }'
5-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 [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}

List Refunds

List refunds available on your integration.

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Query Parameters
Show optional parameters
reference String	Identifier for transaction to be refunded
currency String	Three-letter ISO currency. Allowed values are: NGN, GHS, ZAR or USD
from Date	A timestamp from which to start listing refund e.g. `2016-09-21`
to Date	A timestamp at which to stop listing refund e.g. `2016-09-21`
perPage Integer	Specify how many records you want to retrieve per page. If not specify we use a default value of 50.
page Integer	Specify exactly what refund you want to page. If not specify we use a default value of 1.

1curl https://api.paystack.co/refund
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET

1{
2  "status": true,
3  "message": "Refunds retrieved",
4  "data": [
5    {
6      "id": 1,
7      "integration": 100982,
8      "domain": "live",
9      "transaction": 1641,
10      "dispute": 20,
11      "amount": 500000,
12      "deducted_amount": 500000,
13      "currency": "NGN",
14      "channel": "migs",
15      "fully_deducted": 1,
16      "refunded_by": "[email protected]",
17      "refunded_at": "2018-01-12T10:54:47.000Z",
18      "expected_at": "2017-10-01T21:10:59.000Z",
19      "settlement": null,
20      "customer_note": "xxx",
21      "merchant_note": "xxx",
22      "created_at": "2017-09-24T21:10:59.000Z",
23      "updated_at": "2018-01-18T11:59:56.000Z",
24      "status": "processed"
25    },
26    {
27      "id": 2,
28      "integration": 100982,
29      "domain": "test",
30      "transaction": 323896,
31      "dispute": 45,
32      "amount": 500000,
33      "deducted_amount": null,
34      "currency": "NGN",
35      "channel": "migs",
36      "fully_deducted": null,
37      "refunded_by": "[email protected]",
38      "refunded_at": "2017-09-24T21:11:53.000Z",
39      "expected_at": "2017-10-01T21:11:53.000Z",
40      "settlement": null,
41      "customer_note": "xxx",
42      "merchant_note": "xxx",
43      "created_at": "2017-09-24T21:11:53.000Z",
44      "updated_at": "2017-09-24T21:11:53.000Z",
45      "status": "pending"
46    }
47  ]
48}

Fetch Refund

Get details of a refund on your integration.

Headers
authorization String	Set value to `Bearer SECRET_KEY`

Path Parameters
reference String	Identifier for transaction to be refunded

1curl https://api.paystack.co/refund/:reference
2-H "Authorization: Bearer YOUR_SECRET_KEY"
3-X GET

1{
2  "status": true,
3  "message": "Refund retrieved",
4  "data": {
5    "integration": 100982,
6    "transaction": 1641,
7    "dispute": null,
8    "settlement": null,
9    "domain": "live",
10    "amount": 500000,
11    "deducted_amount": 500000,
12    "fully_deducted": true,
13    "currency": "NGN",
14    "channel": "migs",
15    "status": "processed",
16    "refunded_by": "[email protected]",
17    "refunded_at": "2018-01-12T10:54:47.000Z",
18    "expected_at": "2017-10-01T21:10:59.000Z",
19    "customer_note": "xxx",
20    "merchant_note": "xxx",
21    "id": 1,
22    "createdAt": "2017-09-24T21:10:59.000Z",
23    "updatedAt": "2018-01-18T11:59:56.000Z"
24  }
25}