Skip to main content
A customer with several unpaid orders (loans, invoices, instalments) pays by bank transfer. A single account per customer tells you who paid, but not which order the money is for. Give each order its own account, bound to your order reference, and every payment notification names the order.

The idea

A customer, CUST-10293 in your system, has 10 unpaid orders. You open 10 accounts, one per order, each bound to your order reference. When money lands in one, the account.funded webhook carries that order’s reference, so you mark exactly that order paid. You use your own ids throughout. You never need to store ours.

Choose the kind of account

Steps

1

Name the customer by your own id

Send your customer id as customer_id. The first time, include the customer’s details and the customer is created with your id as their reference (see Use your own customer ids). After that, your id alone is enough. Your id is the customer: a new id creates a new customer even if another of your customers has the same email, so keep one id per person.
2

Open one account per order

Persistent:
Or dynamic:
Repeat for each order with its own reference. Repeating a request for the same order returns the same account, so retries are safe.
3

Show each order's account to the customer

Store the account number against the order and show it next to that order.
4

Match each payment on the webhook

On account.funded, look up the order by data.reference. Compare paid_amount with what the order is owed (expected_amount on dynamic accounts), then mark the order paid once, keyed on transaction_ref so a repeated webhook can’t apply twice.
(Abridged; see account.funded for every field.)
5

Verify when in doubt

POST /v1/payments/verify with the order reference returns the payment, or order_unpaid if nothing has been paid into that order’s account yet.

When the bank can’t open more accounts

Some banks can issue only one account per customer. If the customer already holds an account at such a bank, opening another answers 409 account_limit_reached, and data.accounts lists the customer’s existing accounts there. Nothing is opened. Either:
  • choose another bank with codes on the request, or
  • use dynamic accounts for the orders, which are not limited this way.
A person can also hold at most 20 open persistent accounts with your business by default, counted across every customer id that shares their BVN. One more answers 409 account_limit_reached with data.limit and data.active. Dynamic accounts expire and don’t count; contact support if you need a higher limit.

Things to know

  • Different amounts are credited. A transfer that doesn’t match the order is still credited (less our fee). Decide in your system what an underpayment or overpayment means for the order.
  • Several transfers into one account are each credited, each with its own webhook.
  • Late payments are credited. A payment into a dynamic account after expires_at is credited and marked "late": true on the webhook.
  • An account without a reference identifies the customer, not the order. Payments into it carry customer_reference but no reference.
  • References are yours, and private to your business. Another business using the same reference never sees your accounts or payments.