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 (Abridged; see account.funded for every field.)
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.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 answers409 account_limit_reached, and data.accounts lists the customer’s existing accounts there. Nothing is opened. Either:
- choose another bank with
codeson the request, or - use dynamic accounts for the orders, which are not limited this way.
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_atis credited and marked"late": trueon the webhook. - An account without a reference identifies the customer, not the order. Payments into it carry
customer_referencebut noreference. - References are yours, and private to your business. Another business using the same reference never sees your accounts or payments.

