Use the top-up API to create a funding invoice or maintain an automatic top-up policy. Creating an invoice does not mark it paid, and saving a policy does not itself charge a card. Reconcile billing outcomes separately from the API request that initiated them.
IN THIS ARTICLE
01 Choose manual funding or a policy
| Method | Resource | Scope | Idempotency-Key |
|---|---|---|---|
GET |
/v2/topup-profile |
wallet:read |
Not required by this route |
PUT |
/v2/topup-profile |
wallet:write |
Required |
POST |
/v2/topups |
wallet:write |
Required |
For manual funding, POST a positive decimal amount and optionally an owned wallet_id. The account default wallet is used when none is supplied. Store the resulting invoice or resource reference and complete payment through the supported billing workflow.
02 Configure automatic top-up carefully
- GET the current policy, allowing for the possibility that none exists.
- Choose the intended
currency_id, enabledgateway_moduleand payment method owned by the billing customer. - Set the threshold, individual top-up amount, daily limit and monthly limit as explicit decimal values.
- Keep
statuspaused while verifying those values and the gateway's eligibility for the intended charging workflow. - Submit the reviewed policy with its idempotency key and current
If-Matchversion where available. Read it back. - Enable only the supported policy state after the billing identity, consent and payment method have been checked in the authorised setup process.
Why did I get an invoice but no extra credit?
An unpaid invoice is only a funding request. Even after payment, its recorded settlement must be reconciled to the intended account and wallet. Inspect the invoice and wallet ledger before submitting a second top-up. Preserve the original idempotency key if retrying an identical uncertain request.
Can I supply another customer's payment method ID?
No. Payment methods must belong to the authorised billing customer. A numeric identifier copied from another account does not confer permission to charge it.
If an automatic top-up is not running, check policy state, eligible gateway, payment method and limits. Avoid raising limits as the first troubleshooting step. A paused or capped policy may be working exactly as intended.