Top-ups

A top-up adds credits to a customer’s wallet outside the normal plan refill — the customer is running low and wants more now. UnitPay grants the credits and settles the money; the only question is how the money moves.

​

How a top-up settles

A self-serve customer has a saved payment method, so a top-up charges it right away:

1. Charge the saved card via the PSP for the top-up amount.
2. Grant the credits once the charge succeeds.

Money in, then credits out — the balance reflects the purchase immediately. If no card is on file yet, the charge collects one in the browser first (the same card-on-file flow a subscription uses), then grants.

​

Auto top-ups

Auto top-ups make the refill automatic: when a balance falls below a threshold after a usage event, UnitPay purchases more credits without the customer lifting a finger — preventing service interruptions for customers who don’t want to manage a balance by hand. You configure a per-feature threshold and a quantity to purchase (PUT /v1/customers/:id/auto-topup-rules/:creditCurrencyId); the charge hits the saved card. Purchase limits cap runaway spend, and burst suppression prevents duplicate purchases from rapid-fire usage.

​

Credit packages

A credit package is a pre-defined bundle of credits a customer buys as a self-serve top-up (priority 50 in the grant convention — preserved behind plan credits as a buffer). Packages are the manual counterpart to auto top-ups: the customer picks a bundle and checks out, and the same collectionMethod branch decides charge-now vs. invoice. For a $-denominated wallet, a package is priced so one credit equals one minor currency unit — see Denominations.

​

In your app

The React credit hooks cover the whole top-up surface — reading balances, buying a package, triggering a top-up, configuring auto top-ups, and showing history.

​

See also