Plan partner wallet balance for bill payment API traffic
Read the partner balance, distinguish it from customer collections and account for concurrent purchases when planning funding and low-balance responses.
Already registered? Open API settings and follow the business-access steps. Sandbox purchases do not deliver real services.
Reviewed
Your checkout can collect a customer's money while your partner account has too little available balance to buy the bill product. Treat those two balances separately so a funding problem does not become an unexplained customer payment.
Read the right balance
Call GET /account/balance with the read_balance scope. The response places the amount at data.balance, alongside data.currency and data.updated_at. Keep the amount as a decimal value or convert through a deliberate minor-unit representation; do not use a floating-point total as your accounting record.
The sandbox returns a simulated balance. It can help test response parsing and screen states, but it does not measure available production funds or establish that your live funding process works.
A balance read is a snapshot
Two workers can read the same available balance before either submits an order. A successful read does not reserve funds for both purchases. Plan concurrency in your own queue and handle a rejected purchase according to its actual result.
| Question | Record to consult |
|---|---|
| Has the customer paid my business? | Your customer collection record |
| Can the partner account currently fund purchases? | The available balance response |
| What did this purchase debit? | The transaction's recorded price breakdown |
| Has an unresolved purchase completed? | Its current transaction status |
| Has the customer been refunded? | The relevant customer refund and ledger record |
Do not calculate spendable funds by adding the retail prices of pending orders. The retail amount can include your markup, and some customer payments may still be unsettled or subject to a refund.
Define the low-balance response
Choose an internal operating threshold based on actual purchase costs, your funding lead time and observed demand. Assign someone to respond when it is crossed. This is an operating decision for your business, not a balance guarantee supplied by the API.
If the account cannot support a new order, pause new submissions cleanly. For a customer who already paid, preserve the order and follow your stated fulfillment or refund process. Do not ask them to pay again to resolve a partner-funding issue.
Before enabling live traffic, verify the real funding route through your approved account process, confirm who monitors it and rehearse how support finds affected orders. Keep automated funding or balance alerts within capabilities you have actually configured and tested.
Reconcile balance changes with transaction records rather than inferring all activity from a single before-and-after difference. Other purchases and account movements may occur between those two reads.