Skip to main content
Current support: Solana only. Sui wallet payments are marked coming soon and disabled on the backend (WALLET_CONNECT_SUI_ENABLED=false). The existing Sui address/QR checkout still works.
“Pay with wallet” is additive. Copy-address, QR, “I have paid”, manual verification, under/overpayment and wrong-asset refunds all keep working.
The wallet UI is gated by WALLET_CONNECT_PAY_ENABLED=true on the backend and NEXT_PUBLIC_WALLET_PAY_ENABLED=true on the frontend. Both default to off.

​
Flow

  1. Customer selects a network/asset and reaches the deposit step as usual.
  2. Pay with wallet opens Wallet Standard discovery (Phantom, Solflare, Backpack, MetaMask, OKX, etc.).
  3. Backend POST /wallet-connect/preflight checks token balance, gas (SOL) and token-account existence. Human-readable problems are returned before any signing.
  4. Backend POST /wallet-connect/build-payment-tx builds an unsigned transaction to the checkout’s unique deposit address. The backend never holds customer keys.
  5. The customer sees a Review payment screen, then clicks Approve in wallet. That click opens their wallet’s native approval popup.
  6. The wallet signs and submits. The frontend then verifies the deposit on-chain through the existing checkout verify endpoint and moves to Payment successful automatically, including the merchant redirect.
  7. The existing blockchain listener remains the source of truth for reconciliation.
Phantom and Solflare use their injected providers for reliable popups; other wallets use Wallet Standard. No automatic timeout or auto-cancel: the connection stays open until the user closes it. Connections are recorded in wallet_connections with purpose, linked payment/subscription and a hashed user agent. No raw IP is stored. Connections appear in Logs → Wallet and in Admin → Connected Wallets.

​
Errors

WALLET_NOT_FOUND, USER_REJECTED, WRONG_NETWORK, INSUFFICIENT_TOKEN_BALANCE, INSUFFICIENT_GAS, TOKEN_ACCOUNT_MISSING, TX_EXPIRED, RPC_UNAVAILABLE, SIMULATION_FAILED, PAYMENT_EXPIRED, PAYMENT_ALREADY_PAID, UNKNOWN. Each maps to a title, a one-line fix and a retry action. Raw RPC errors are logged server-side and never shown to customers.

​
Subscription approvals

The same pipeline is reused for subscription authorization and customer-portal actions:
  • Solana: capped ApproveChecked delegate approval (never unlimited). The cap is amount × min(max_cycles, 12).
  • Sui: coming soon.
The wallet-standard discovery layer is deliberately swappable: adding a chain means adding one adapter/provider, not editing checkout.