Refunds

The RefundResource allows you to create and manage transaction refunds. You can initiate refunds, retry failed refunds, and list or fetch refund details.

Create Refund

Initiate a refund on your integration.

$refund = paystack()->refund()->create([
    'transaction' => 'T685312322670591', // Transaction reference or ID
    'amount' => 5000, // Amount in subunits (e.g., 50.00)
    'currency' => 'GHS',
    'customer_note' => 'Product returned',
    'merchant_note' => 'Refund approved by manager'
]);

Body Parameters

Parameter	Type	Required	Description
transaction	String	Yes	Transaction reference or ID.
amount	Integer	No	Amount to be refunded in subunits. Defaults to original transaction amount. Cannot be more than the original amount.
currency	String	No	Currency of the refund (e.g., NGN, GHS, ZAR, USD).
customer_note	String	No	Reason for refund visible to the customer.
merchant_note	String	No	Internal reason for the refund.

Retry Refund

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

$refundId = 1234567;

$response = paystack()->refund()->retry($refundId, [
    'currency' => 'NGN',
    'account_number' => '1234567890',
    'bank_id' => '9'
]);

Parameters

Parameter	Type	Required	Description
refund_account_details	Object	Yes	An object containing currency, account_number, and bank_id.

List Refunds

List refunds available on your integration.

// List all refunds
$refunds = paystack()->refund()->list();

// Filter refunds
$filtered = paystack()->refund()->list([
    'transaction' => '1641',
    'currency' => 'GHS',
    'from' => '2023-01-01',
    'to' => '2023-12-31'
]);

Fetch Refund

Get details of a specific refund.

$refundId = 3018284;
$details = paystack()->refund()->fetch($refundId);

Use Cases

Full Refund

Refund the entire transaction amount.

paystack()->refund()->create([
    'transaction' => 'TRANS_REF_123'
]);

Partial Refund

Refund only a portion of the transaction amount.

paystack()->refund()->create([
    'transaction' => 'TRANS_REF_123',
    'amount' => 2000 // Refund 20.00
]);

Handling Failed Refunds

If a refund fails with needs-attention (often due to invalid account details for the reversal), you can retry it with new account details.

$refundId = 12345; // ID of the failed refund

paystack()->refund()->retry($refundId, [
    'currency' => 'NGN',
    'account_number' => '0000000000', // Correct account number
    'bank_id' => '057' // Zenith Bank
]);