Paying suppliers with Paystack Transfers
How a Nigerian business pays suppliers through Paystack's Transfer API, from recipients and references to retries, and how to record each payment.
By Achekam · · 4 min read · For Running a business businesses in Nigeria
Once a business is collecting through Paystack, it is tempting to pay suppliers from the same place. The money is already there, and Paystack's Transfer API lets a developer send it to any Nigerian bank account from your own systems. For a business paying many small suppliers, riders or agents, that can save hours of keying payments into a banking app.
It also moves a sensitive job, deciding who gets paid, into software. This article explains how Paystack's transfers work as its documentation describes them, the reference rule that prevents paying a supplier twice, the test-mode trap, and how to keep the payment record in Achekam honest and the controls around it tight.
Step one: a transfer recipient
Paystack's documentation sets out four steps for a single transfer: create a transfer recipient, generate a transfer reference, initiate the transfer, and listen for the transfer status.
The recipient comes first. Before sending money with the Transfer API, you create a transfer recipient from the beneficiary's details, using the nuban type for Nigerian bank accounts in NGN. Paystack returns a recipient_code, which its documentation says you should save with your records.
A recipient is, in effect, a saved payee. Once it exists, money can be sent to it again and again with no further check on the bank details. That makes the moment of creating a recipient the moment to be careful.
Unique references, and retrying with the same one
Every transfer needs its own reference. Paystack's documentation says each reference should be 16 to 50 characters long and contain only lowercase letters, digits, underscores and dashes, and it recommends a v4 UUID.
The reference is also your protection against paying twice. Paystack says that if a transfer request errors, you should retry it with the same reference to avoid double crediting, because a transfer with a new reference is treated as a new request.
Picture a network error just after you send a supplier's payment. You do not know whether it went. If your system tries again with a fresh reference, and the first attempt had in fact succeeded, the supplier is paid twice. Retrying with the original reference lets Paystack recognise the request it has already seen.
Success, failed and reversed
Paystack's documentation says live transfers usually take between a few seconds and a few minutes to process, after which Paystack sends one of three events to your webhook URL: transfer.success, transfer.failed or transfer.reversed. It sends transfer.reversed when it refunds a previously debited amount for a transfer that couldn't be completed. It also advises updating a transfer's status from data.status only when the response has a 200 status code.
For the supplier ledger, only transfer.success means the supplier was paid. A failed transfer means they were not. A reversed transfer means they were not, and the money came back to you. Anything recorded as paid on the strength of an attempt, rather than a success, will have to be undone.
Test transfers always succeed
Paystack's documentation says test transfers always return success. That is helpful for a developer and dangerous for anyone signing off a new system. A test run that "paid" every supplier proves the code connects; it proves nothing about bank details, balances or what happens when a transfer fails. Before going live, make the first real transfers small and check each one arrived.
Paystack describes recipients, references, retries and transfer events on its single transfers documentation page, which does not state transfer fees or limits; ask Paystack for those.
Recording the payment in Achekam
Achekam does not send supplier payments, through Paystack or anywhere else. Paying a supplier in Achekam only records the payment, and no bank payment file is produced for suppliers.
What Achekam holds is the bill. A business records supplier bills line by line with VAT, a bill without a purchase order waits for approval before it posts, and a bill can be paid in full or in parts from a chosen bank account. When a Paystack transfer succeeds, record the payment against the bill, choosing the account the money actually left, and put the Paystack transfer reference in the payment's reference so the two can be matched later.
Record only on success. If a transfer is still processing at the end of the day, leave the bill open until the outcome arrives.
Separating who sets up recipients from who releases payments
Paystack transfers concentrate two powers that should sit with different people: deciding where money can go, and deciding that it goes.
Achekam applies this split in payroll. An employee's bank account entered or changed by one person must be verified by another person before it is paid in the payment schedule or bank file. No equivalent rule is described for supplier recipients in Paystack, so build the same discipline into how your team uses it:
| Task | Who |
|---|---|
| Request a new supplier recipient, with bank details confirmed by phone | Accounts clerk |
| Verify the details and approve the recipient | A second person |
| Approve the bill in Achekam | The bill approver |
| Release the transfer | Someone other than the person who created the recipient |
| Record the payment with the Paystack reference | Accounts clerk, after success |
Write that division down, and settle who can do what in Paystack, before the first live supplier transfer. A safe routine for checking the beneficiary's name before paying is in paying suppliers by NIP transfer safely, and how money reaches your own account from Paystack is in Paystack payouts: which bank account and limits.
General guidance only, not advice on your own circumstances. Tax and payroll rules change: check the current position with the authority or your adviser.
