Building a Crypto Wallet Top-Up Flow (Complete Guide)

The top-up funnel

A wallet top-up flow is one of the highest-intent moments in a crypto product — the customer has already decided they want more credit and is actively looking for the button. That doesn't mean the funnel is easy. The typical drop-off path looks like this:

1. Customer clicks the top-up button.
2. Picks an amount (or types one).
3. Sees a deposit address or QR code.
4. Opens their wallet.
5. Sends the transfer.
6. Waits for confirmation.
7. Sees the balance update.

Any of steps 3 through 7 can lose the customer. The rest of this piece walks through how to keep them at each step, and what a production-grade Solpaygate integration looks like when done well.

Deposit address per order

Do not reuse a single deposit address across customers or orders. Each top-up should get a freshly generated address that maps one-to-one to a specific order in your database. There are three reasons for this: it lets you match incoming transactions to the right customer without them needing to attach a memo; it prevents cross-tenant confusion when two customers pay similar amounts within the same block; and it isolates the blast radius if any one address is ever compromised.

With Solpaygate this is the default — the payment-session endpoint returns a fresh address every call, and funds are auto-swept to your master wallet within seconds of confirmation. Your code never has to manage keys.

Confirming and crediting

Confirmation is the moment the payment turns into balance. Get this wrong and customers see "waiting for confirmation" indefinitely, refresh the page, and come back three times to check.

The right pattern uses two channels: your server credits the account on the incoming webhook (source of truth), and your frontend either polls the payment status or listens on a WebSocket to update the UI in real time. If your webhook handler is idempotent — keyed on the paymentId — you can safely let both channels fire without double-crediting.

Crediting checklist

• Verify the webhook signature before doing anything with the payload.
• Match by paymentId, not by amount.
• Wrap the credit and the payment-marked-as-processed update in one database transaction.
• Convert to your reporting currency at the confirmation rate, not at address-issue time.
• Send a confirmation email or in-app notification within a second of crediting.

Post-payment UX

The 30 seconds after the customer signs the transaction is where a lot of confidence is won or lost. Show live status: "Detected on chain — waiting for confirmations" then "Confirmed — crediting your balance" then "Done — balance updated to $150.00." Actual state transitions, not a generic spinner.

If you configured a returnUrl on the session, Solpaygate sends the customer back to your app after payment. Land them somewhere useful — a "balance updated" screen or their dashboard — not the same top-up page they started on. And avoid modals that vanish on refresh; put the confirmation on its own route so the customer can share, screenshot, or come back to it.

Common pitfalls

A few things trip up teams building their first top-up flow:

• Address expiry is real. Solpaygate addresses have a 15-minute expiry after issue. If a customer holds a QR code overnight, don't credit that transaction — refund and re-issue.
• Underpayment. Customers occasionally send slightly less than the requested amount (fees, typo, custom amount). Decide up front: partial credit, exact match required, or auto-refund below tolerance.
• Overpayment. Rare but happens. Credit the actual amount received, not the invoiced amount.
• Wallet with no SOL for fees. Warn the customer before they hit the "Send" button in their wallet.
• Mobile flows. Test the return-from-wallet transition on iOS Safari. The tab context sometimes doesn't survive, and your dashboard needs to recover from that.

Webhook design is central to any top-up flow, and it's worth reading the details end-to-end in our webhooks setup guide. Top-up flows are also usually one piece of a broader crypto-payment integration — if you're also thinking about checkout drop-off across the funnel, not just top-ups, start with our piece on reducing crypto payment abandonment.