paystack-refunds（薪资退款）

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

Create Refund

POST /refund

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.

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

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

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