Skip to content

Knowledgebase

Create funding invoices and configure an automatic top-up policy

domain-nexus, development

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.

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

  1. GET the current policy, allowing for the possibility that none exists.
  2. Choose the intended currency_id, enabled gateway_module and payment method owned by the billing customer.
  3. Set the threshold, individual top-up amount, daily limit and monthly limit as explicit decimal values.
  4. Keep status paused while verifying those values and the gateway's eligibility for the intended charging workflow.
  5. Submit the reviewed policy with its idempotency key and current If-Match version where available. Read it back.
  6. 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.

Was this answer helpful?

Need a little more help?

Our support team can help you find the next step.

Contact support