Paystack reversals and chargebacks in your books
What a reversed Paystack transaction means, how refunds and chargebacks show up as payout deductions, and how a Nigerian business should book them.
By Achekam · · 4 min read · For Running a business businesses in Nigeria
The payout from Paystack is smaller than the payments you expected. You check the dashboard and find a transaction marked "Reversed" that was a perfectly good sale last month. Was it refunded? Did the customer dispute it with their bank? And what should the books say about an invoice that was paid, and now apparently is not?
A reversal is one of the few events that pulls money back out of a sale you thought was finished. This article explains what Paystack means by a reversed transaction, how reversals and chargebacks show up on payouts, the status trap that catches people who check transactions by hand or by code, and how a Nigerian business should record each case in Achekam.
What "reversed" covers
Paystack's documentation says a transaction status of "reversed" means the transaction was reversed, which could mean it was refunded or a chargeback was successfully logged for it.
Those are two very different events:
- A refund is something your business chose to do, usually with the customer's agreement.
- A chargeback is something the customer's bank did, usually because the customer disputed the payment.
Both end with the money leaving you, and both show the same status. Your first job with any reversed transaction is to find out which it was.
Paystack lists the other statuses a transaction can carry as abandoned, failed, ongoing, pending, processing (for direct debit), queued (for bulk charges only) and success.
Reversal pending, reversed, or back to success
Refunds pass through stages. According to Paystack's refunds documentation, while a refund is pending, processing or needing attention, the transaction shows Reversal Pending, and once processed it shows Reversed. When a refund cannot be processed, your Paystack account is credited with the refund amount and the transaction's status returns to Success.
So a status can change after you have looked at it. A transaction you saw as Reversal Pending on Monday may be Reversed by Friday, or back at Success if the refund failed. Check again before you close the month.
Deductions on the payout
Paystack says the amount of each payout is the sum of all payments made to you, minus transaction fees, and that the payout details show deductions such as refunds or chargebacks. A CSV export of the payout lists each transaction in it.
That export is the document to work from. When a payout is short, open its details, find each deduction, and note for each one the original transaction, the customer, the amount and whether it was a refund or a chargeback.
The status trap
If someone in your business, or a developer you work with, checks Paystack transactions through its verify API, there is a warning in Paystack's documentation worth repeating. The response.status key of the verify response shows the status of the API call, not of the transaction. The transaction's own status is in response.data.status.
A check that reads the wrong field can report that all is well because the call itself worked, while the transaction it asked about was reversed. Paystack sets out the statuses and that warning on its verify payments page.
How the original payment sits in Achekam
To fix a reversal, you need to know what was booked in the first place.
In Achekam, a verified gateway payment is recorded as a receipt against the invoice, debiting that gateway's clearing account and crediting trade receivables, and the invoice shows as paid or part-paid. Payouts from each gateway are then recorded against the gateway's clearing account with its fees, by hand or from Paystack's own payout list.
So when a payout arrives short because of a reversal, the clearing account will not empty: it still holds the original payment that Paystack has now taken back. The reversal has to be recorded to bring it into line.
Booking each kind of reversal
A refund you made. The money went back by your choice. If the sale was reduced, issue a credit note: in Achekam a credit note is issued from the invoice it corrects, in full or for chosen lines, and posted to the ledger. If the sale stands and the money went back for another reason, such as a duplicate payment, an administrator refunds or reverses the receipt.
A chargeback you accept. If the customer's complaint was fair, for example goods never arrived, treat it like a refund: credit note for the sale, and the receipt reversed so the clearing account matches what Paystack kept.
A chargeback you dispute or cannot recover. If the customer still owes you, reverse the receipt so the invoice shows as unpaid again and chase it like any other debt. If it cannot be collected, an unpaid debt can be written off once a partner approves it. A write-off is not a credit note: it says the customer owed the money and you have given up collecting it.
In each case the reference to use is Paystack's, and the description should say which kind of reversal it was.
A monthly reversals review
- Export each payout's transaction list from Paystack.
- List every deduction: transaction, customer, amount, refund or chargeback.
- Check each original receipt in Achekam against its invoice.
- Record the right correction: credit note, receipt reversal or write-off.
- Confirm the Paystack clearing account now holds only payments not yet paid out.
- Recheck any Reversal Pending transactions before closing the month.
The refund side in detail is in refunding a Paystack payment on an invoice, and payout fees across gateways are compared in gateway payouts and fees.
General guidance only, not advice on your own circumstances. Tax and payroll rules change: check the current position with the authority or your adviser.
