Skip to main content

Wallet movements and customer transactions (ledger alignment)

Overview​

customer_transaction rows are the billing / GL-style ledger for the CRM. wallet_ledger remains the operational wallet history. For card wallet top-up and admin cash / manual wallet credit, the API now creates a matching customer_transaction with negative retail_cost (funds received), payment_type set to:

  • wallet_topup_card: top-up via charged payment method (POST /crm/wallet/topup)
  • wallet_topup_cash: manual credit (POST /crm/wallet/credit, e.g. cash / bank)
  • wallet_adjustment_debit: admin wallet debit (POST /crm/wallet/debit) posts a positive line (adjustment charge)

Each line stores wallet_ledger_id pointing at the corresponding wallet_ledger row for reconciliation.

Sign convention vs GAAP​

In this subledger, negative retail_cost means a line that reduces net charges from the customer’s perspective (e.g. wallet top-up / payment-style credits); positive means a charge-like line (e.g. invoice, wallet adjustment debit). That is a CRM billing convention, not a substitute for formal GAAP presentation.

US GAAP does not mandate this particular sign for internal tables. Compliance depends on double-entry in the general ledger, account mapping (cash, AR, unearned revenue, etc.), and financial statement preparation, not on whether customer_transaction.retail_cost uses plus/minus. For operators, prefer UI that shows absolute amount + label and optionally a running balance, rather than relying on raw sign alone. The billing All Transactions table formats retail_cost with a bold amount and a superscript Cr / Dr (credit / debit charge; tooltips spell this out) plus green/red under the column Owed / credit, so type is not conveyed by color alone. Dr here means a charge to the customer (amount owed), not “your card was debited.”

Pay invoice from wallet​

Pay Invoice includes Wallet only when the customer has a positive wallet balance; it calls POST /crm/payments/invoice with routing_mode: wallet_only (full amount must be covered). Saved card still uses hybrid routing: wallet is applied first, then the card for any remainder.

Auto-deduct wallet when an invoice is created?​

Not implemented by default. Prepaid vs postpaid is a business rule: silently zeroing wallet when an invoice is issued can surprise customers and complicates partial payments, credits, and disputes. Safer pattern: issue the invoice, then explicitly pay (wallet-only, card, hybrid, or staff manual types). If product later needs auto-apply, add a clear setting (e.g. per customer or per invoice) and document GL impact.

Postpaid​

Wallet credits reduce customer.outstanding_balance up to the credited amount (for customer_payment_type = postpaid).

Invoicing​

Uninvoiced wallet-sync lines are customer prepayments. The Generate Invoice preview on the invoice list excludes lines whose payment_type starts with wallet_ so routine invoices are not accidentally reduced by prepayment credits. To apply a prepayment to a specific invoice, use a workflow that selects explicit transaction_ids (if your tooling supports it), or handle adjustments outside this default preview.

Tax: New invoices from outstanding transactions store customer_invoice.retail_cost = sum(line retail_cost) + sum(line tax_amount) (amount due). List/detail API responses also recompute that total from linked lines so older invoices without tax folded into retail_cost still show and charge the correct amount. PDF subtotal/tax/footer use line items, not the raw invoice header alone.

Permissions​

  • POST /crm/wallet/topup: authenticated users who can use the app (customers use card top-up).
  • POST /crm/wallet/credit and POST /crm/wallet/debit: require manage_customer_wallet (granted to admin and customer_service_agent_2 in default role seeds). Re-run populate_roles_permissions (or equivalent) after deploy so the permission exists and is assigned.

Manual “credit” in Add Transaction​

The UI no longer offers manual credit transaction entry, because it did not credit the wallet. Use Billing → Wallet → Cash / manual (staff) or invoice payments instead.