payram-topup-wallet-integration
PayRam Top-Up Wallet Integration (recommended for existing apps)
New store with no payment history? Use the checkout/plugin path (
payram-checkout-integration, or the WooCommerce plugin). Existing app with users and invoices? Use THIS pattern.
Why top-up-first, not pay-per-invoice
Crypto payments are approximate by nature. A customer paying a $50 invoice may send $49.20 (gas mental-math), $60 (round number), $50 in two transfers, or the right amount two hours after the link "expired" — the funds still arrive on-chain. If you bind payments directly to invoices, every one of those is an exception you must code for.
The top-up pattern flips it: whatever arrives is credited to the user's wallet balance — exactly the amount received. Invoices are then debited from the balance as a plain, atomic app-side operation. Every crypto quirk becomes a balance state, not a payment failure:
| Crypto reality | Direct-to-invoice | Top-up wallet |
|---|---|---|
| Overpayment (OVER_FILLED) | Refund flow needed | Excess stays as balance for next invoice |
| Underpayment (PARTIALLY_FILLED) | Failed payment, retry whole amount | Balance credited; top up just the difference |
| Two partial sends | Manual matching | Both credit; invoice settles when balance suffices |
| Late payment after "expiry" | Orphaned funds | Still credited; user spends it normally |
| Refund requested | On-chain refund per payment | App-side reversal entry (+ PayRam payout only if crypto must leave) |