PAYMENTS.md

Payment QR codes

The payment scanner decodes QR payloads in Core and opens confirmation, recipient review, or asset selection based on the result.

Open the scanner from the wallet screen and scan this page from another device. Use a test wallet and do not submit these example transactions.

Supported formats

Type	Supported fields	Core implementation
Plain address and BIP-21-style URI	Raw addresses or recognized chain schemes with amount and memo. XRP accepts xrp:, ripple:, xrpl:, and destination tag dt	BIP-21-style decoder
ERC-681	EVM native transfers and token transfer with address and uint256	ERC-681 decoder
Solana Pay	SOL and SPL-token transfers with amount, spl-token, repeated reference, and memo	Solana Pay decoder
TON transfer	Native TON transfer with atomic amount and text comment	TON decoder

How decoding works

flowchart TD
    Scan["Scanned text"] --> Action["URL action router"]
    Action -->|"wc:"| WalletConnect["WalletConnect"]
    Action -->|"gem:// or gemwallet.com"| Deeplink["Gem deeplink"]
    Action --> Decoder["Payment decoder"]
    Decoder --> Scheme{"URI scheme"}
    Scheme -->|"ethereum:"| ERC681["ERC-681"]
    Scheme -->|"solana:"| Solana["Solana Pay"]
    Scheme -->|"ton:"| TON["TON transfer"]
    Scheme -->|"Supported chain scheme"| BIP21["BIP-21-style decoder"]
    Scheme -->|"No scheme"| Address["Plain address request<br/>No asset selected"]
    Solana -->|"HTTPS transaction request"| PaymentReview["Open review request<br/>Loading"]
    PaymentReview --> Gateway["Load merchant and transaction"]
    Gateway --> Confirm["Open confirmation"]
    Confirm --> Simulation["Preload and simulate concurrently"]
    ERC681 & Solana & TON & BIP21 & Address --> Request{"Payment request?"}
    Request -->|"No"| Reject["Not supported"]
    Request -->|"Yes"| Assets{"Matching wallet assets"}
    Assets -->|"None"| Reject
    Assets -->|"Multiple"| Select["Asset selection"]
    Assets -->|"One, signable amount + memo when required"| Confirm["Confirmation"]
    Assets -->|"One, amount or required memo missing/unusable"| Recipient["Recipient review"]

Loading

Routing is decided in Core by payment_destination: it matches wallet assets, validates and checksums the address, converts the amount exactly (excess precision is never rounded), and requires a memo only on chains where the QR tag identifies the deposit (Cosmos, TON, XRP, Stellar, Algorand). Solana Pay transfers confirm without a memo.

WalletConnect and Gem deeplinks are routed before payments. Solana transaction links load the merchant and encoded transaction through the payment service before opening confirmation. Confirmation then preloads the transaction and simulates it concurrently using the same transaction simulation service as WalletConnect.

Static Solana Pay transfer requests use the regular transfer flow. Each reference is preserved in URL order and added to the SOL or SPL-token transfer instruction as a read-only, non-signer account. A memo is emitted as the instruction immediately before the transfer.

Core entry points:

• URL action routing
• Payment decoder dispatch
• Payment service
• UniFFI bridge

Payment flows

Bitcoin amount bitcoin:bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4?amount=0.0001 Confirm 0.0001 BTC.	Bitcoin address only bitcoin:bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4 Open the recipient screen.
Plain EVM address 0x1f9090aaE28b8a3dCeaDf281B0F12828e676c326 Select an asset when multiple EVM chains match.	Ethereum USDC ethereum:0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48@1/transfer?address=0x1f9090aaE28b8a3dCeaDf281B0F12828e676c326&uint256=1500000 Confirm 1.5 USDC.
Solana USDC solana:HA4hQMs22nCuRN7iLDBsBkboz2SnLM1WkNtzLo6xEDY5?amount=1&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v Confirm 1 USDC.	XRP destination tag ripple:rEb8TK3gBgk5auZkwc6sHnwrGVJH8DuaLh?amount=10&dt=12345 Confirm amount 10 with tag 12345.
TON comment ton://transfer/UQA5olhYULHkui4mTQM0LodWG0EqUaxmK6-e3mHrCZFO2diA?amount=1000000000&text=order+7 Confirm 1 TON with comment order 7.	Excess BTC precision bitcoin:bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4?amount=0.000000001 Do not round; open recipient review.

Partially specified payments

These payloads decode successfully but open the recipient screen for review or completion.

XRP without destination tag ripple:rEb8TK3gBgk5auZkwc6sHnwrGVJH8DuaLh?amount=10 Amount 10 is preserved; add a destination tag only if required.	XRP without amount ripple:rEb8TK3gBgk5auZkwc6sHnwrGVJH8DuaLh?dt=12345 Tag 12345 is preserved; enter the amount.

Token tests require the exact token to be enabled in the wallet.