One invoice, many chain-aware attempts
A crypto invoice should be the commercial source of truth: merchant, order, pricing currency, requested amount, expiration, accepted routes, and fulfillment state. Each Bitcoin, Ethereum, Solana, stablecoin, or World Chain instruction is a child payment attempt. This model lets a customer change methods without creating unrelated orders and prevents two successful attempts from being applied silently to one purchase.
Every route must identify the exact network, asset, destination strategy, quote policy, and confirmation profile. The API can normalize the invoice lifecycle while preserving the evidence required by each chain.
Use structured payment instructions
Return separate fields for network, asset, destination, amount, memo or reference, wallet link, QR payload, expiration, and customer warning. Do not compress every chain into an opaque address string. Structured instructions let clients validate and display the route correctly and make it possible to add capabilities without parsing human text.
A Bitcoin route may use a fresh address and output-based evidence. An Ethereum token route may use contract events and log indexes. A Solana route may use a transfer or transaction request with a reference. A World Chain Mini App can request an embedded wallet action. These are different mechanisms under the same commercial invoice.
Define quotes and expiration
If the invoice is priced in fiat and paid with a volatile asset, store the price source, timestamp, spread or fee treatment, rounding, amount, and expiration. Do not change the amount silently while the user prepares a transaction. When the quote expires, create a new attempt and continue monitoring the earlier instruction for late money.
Stablecoins reduce price volatility but do not eliminate route risk. Validate the exact token contract or mint and network. Make the wrong-network warning prominent and explain how late, partial, excess, or unsupported transfers are handled.
Observe settlement with chain-specific evidence
Adapters emit normalized observations containing network, transaction identifier, sub-index, source, destination, asset, amount, block or slot reference, transaction status, and first-seen time. A confirmation service applies route policy. This keeps node or indexer details away from the invoice and lets the platform recover from a provider change.
Use real-time events for responsive checkout and scheduled backfills for recovery. Deduplicate with a chain-appropriate key. Preserve reorganization or rollback events instead of deleting the original observation.
Separate detected, confirmed, and available
A wallet can show a transfer before the platform is ready to fulfill. Detection means evidence exists. Confirmation means the evidence meets a versioned network policy. Availability means policy, risk, and operational holds are cleared. Display these states in language the customer and merchant can understand.
For some low-risk products, a platform may reserve inventory after detection and fulfill after stronger confirmation. For high-value or irreversible delivery, it may wait longer. Configure the policy by route and use case rather than scattering thresholds across application code.
Handle partial, excess, duplicate, and late money
Store every transfer and compute how much can be applied. Multiple Bitcoin outputs or token transfers may satisfy one invoice. An excess amount can require merchant acceptance or refund. A duplicate successful attempt after the invoice is paid should enter an exception queue. A late payment should never disappear because the checkout expired.
Define whether a volatile-asset partial payment is valued at the original quote or arrival time. Communicate the rule before checkout and keep the quote version with the payment.
Refund to an authenticated destination
A refund is a new outbound transaction. The apparent source may be an exchange hot wallet, contract, or service that cannot identify the return. Ask the authenticated customer for a supported destination, validate the network and asset, apply policy and approval, and state who bears the fee.
Give the refund its own state machine and settlement evidence. Link it to the original invoice and remaining refundable amount. Treasury movements, gas funding, and wallet sweeps should remain separate from merchant refund records.
Reconcile invoice, ledger, wallet, and chain
Post balanced entries when a payment is recognized and when merchant funds become available. Record platform fees, network costs, conversion, and payout separately. Reconcile the invoice system and ledger to custody balances and independent chain observations.
Useful queues include observed transfers without invoice application, paid invoices without ledger postings, internal wallet movements without treasury records, unsupported tokens at monitored addresses, and refunds without terminal evidence.
Production test matrix
- Customer switches route after opening an earlier payment instruction.
- Same webhook or chain observation arrives multiple times and out of order.
- Partial, excess, duplicate, and post-expiration transfers.
- Wrong token, wrong network, wrong memo, or missing reference.
- Indexer delay, node disagreement, provider outage, and chain reorganization.
- Refund to a verified exchange or custodial destination.
The multi-chain API is ready only when these paths reach a clear financial and customer outcome.
