Paystack Refunds

The Refunds API lets you create and manage refunds for transactions. Supports full and partial refunds.

Depends on: paystack-setup for the paystackRequest helper.
Related: paystack-webhooks for refund.processed, refund.failed, refund.pending events.

Endpoints

Method	Endpoint	Description
POST	`/refund`	Create a refund
POST	`/refund/retry_with_customer_details/:id`	Retry a failed refund
GET	`/refund`	List refunds
GET	`/refund/:id`	Fetch a refund

Create Refund

POST /refund

Param	Type	Required	Description
`transaction`	string	Yes	Transaction reference or ID
`amount`	integer	No	Amount in subunits (defaults to full transaction amount)
`currency`	string	No	Currency code
`customer_note`	string	No	Reason shown to customer
`merchant_note`	string	No	Internal reason for merchant

Full Refund

const refund = await paystackRequest<{
  status: string;
  amount: number;
  transaction: { reference: string; amount: number };
}>("/refund", {
  method: "POST",
  body: JSON.stringify({
    transaction: "T685312322670591",  // Transaction reference or ID
  }),
});
// refund.message → "Refund has been queued for processing"

Partial Refund

await paystackRequest("/refund", {
  method: "POST",
  body: JSON.stringify({
    transaction: "T685312322670591",
    amount: 5000,                        // Refund ₦50 of a larger transaction
    customer_note: "Partial refund for damaged item",
    merchant_note: "Customer reported damage on item #3",
  }),
});

Retry Refund

POST /refund/retry_with_customer_details/:id

Retry a refund with needs-attention status by providing the customer's bank account details.

Param	Type	Required	Description
`refund_account_details`	object	Yes	Customer's bank account details
`refund_account_details.currency`	string	Yes	Currency (same as original payment)
`refund_account_details.account_number`	string	Yes	Customer's bank account number
`refund_account_details.bank_id`	string	Yes	Bank ID (from List Banks endpoint)

await paystackRequest(`/refund/retry_with_customer_details/${refundId}`, {
  method: "POST",
  body: JSON.stringify({
    refund_account_details: {
      currency: "NGN",
      account_number: "1234567890",
      bank_id: "9",
    },
  }),
});

List Refunds

GET /refund

Param	Type	Required	Description
`transaction`	string	No	Filter by transaction ID
`currency`	string	No	Filter by currency
`from`	date	No	Start date e.g. `2016-09-21`
`to`	date	No	End date
`perPage`	integer	No	Records per page (default: 50)
`page`	integer	No	Page number (default: 1)

const refunds = await paystackRequest("/refund?perPage=20&page=1");

Fetch Refund

GET /refund/:id

const refund = await paystackRequest(`/refund/${refundId}`);
// refund.data.status → "pending" | "processing" | "processed" | "failed"

Refund Statuses

Status	Description
`pending`	Refund initiated, awaiting processor
`processing`	Refund received by processor
`processed`	Refund successfully completed
`failed`	Refund failed — your account is credited back
`needs-attention`	Refund needs manual intervention (retry with customer details)

Webhook Events

Listen for these events to track refund lifecycle:

refund.pending — Refund initiated
refund.processing — Refund being processed
refund.processed — Refund completed successfully
refund.failed — Refund failed (amount credited back to your account)

Important Notes

Refund amount cannot exceed the original transaction amount
If amount is omitted, the full transaction amount is refunded
Partial refunds are supported — you can refund a portion of a transaction
Failed refunds credit the refund amount back to your Paystack balance
For needs-attention status, retry with customer's bank account details
Always listen for webhook events rather than polling for refund status

paystack-refunds

Safety Notice

Copy this and send it to your AI assistant to learn