Account Wallet
Understand billing info, payment-method metadata, account balance, credits, refunds, and the current wallet-management gaps.
The Account Wallet is the billing concept that groups stored billing information, payment-method metadata, account balance, credits, refunds, and transaction history under an account.
In the current product, the wallet is partly visible through billing info display, account balance, invoices, transactions, credits, refunds, and payment gateway activity. Full payment-method and wallet management still needs more complete UI support.
Wallet Concepts#
| Concept | What it means |
|---|---|
| Billing info | Stored billing profile data attached to an account, including contact details, billing address, validity, and gateway authorization metadata. |
| Payment method | The card or payment instrument represented by gateway authorization data, such as card type, last four digits, expiry, bank, brand, and gateway signature. |
| Primary payment method | The preferred billing info for automatic collection where the payment flow supports it. |
| Backup payment method | A secondary billing info that can be used when the primary method fails, where configured. |
| Account balance | The account-level balance shown in account information. |
| Credit | A credit note or credit balance that can reduce what the account owes. |
| Refund | A reversal or return of value connected to an invoice or transaction. |
| Transaction | A payment, refund, authorization, external payment, or gateway outcome linked to the account. |
What You Can Review Today#
From the account detail dashboard, your team can review:
- Account balance.
- Primary billing information when it exists on the account.
- Account invoices.
- Account line items.
- Account transactions.
- Credit and refund activity.
- External payments recorded against invoices.
- Credit application to invoices.
- Voucher redemptions.
This gives staff a practical view of the account's billing history even before full wallet management is complete.
Payment Gateway Relationship#
Payment-method metadata comes from the connected payment gateway. A billing info authorization can include details such as:
- Authorization code.
- Card brand or type.
- Last four digits.
- Expiry month and year.
- Bank.
- Country code.
- Reusable token or signature.
For gateway setup, see What is a Payment Gateway?.
Current Product Support#
The shared account model and backend support multiple billing infos and payment-method metadata. The Account detail view can display primary billing info when it exists.
The current UI does not yet expose full wallet management for all expected actions, such as adding, replacing, removing, or choosing primary and backup payment methods directly from the account dashboard. Do not assume customers can self-manage multiple stored payment methods until that workflow is implemented for your tenant.
Credits and Refunds#
Account wallet activity is not limited to payment methods. Credits and refunds are also part of the account billing picture.
Use account credit and refund workflows to:
- Create a credit when the business owes value back to the customer.
- Preview a refund or credit before submitting it.
- Apply credit balance to an invoice.
- Review credit payments and refunded amounts on invoices.
- Keep invoice and transaction history auditable.
Implementation Notes for Future Wallet Completion#
A complete wallet implementation should include:
- Add payment method.
- Update payment method and billing address.
- Remove payment method when allowed.
- Set primary payment method.
- Set backup payment method.
- Choose subscription-specific billing info where needed.
- Show payment-method validity and last gateway authorization state.
- Show account credit balance and available credit actions in one place.
- Explain payment retry and dunning behaviour when automatic collection fails.
- Add audit history for wallet changes.