A multi-chain invoice API should give merchants one coherent workflow while respecting the differences among Bitcoin, Ethereum, Solana, and token transfers. The merchant wants to create an invoice, present a payment instruction, receive a reliable status, and reconcile the result. The payment platform must also manage quotes, address assignment, chain observation, confirmation, partial payments, wrong assets, expiration, refunds, and treasury movement.
The goal is not to make every chain look identical. It is to create a stable commercial model with explicit route capabilities. The crypto invoice hub explains the broader use cases; this guide focuses on the API and operations behind them.
Make the invoice the commercial source of truth
The invoice should record the merchant, order reference, pricing currency, requested amount, accepted routes, quote policy, expiration, customer-facing status, and fulfillment status. A route is a specific combination of network, asset, destination strategy, and confirmation profile. The invoice can offer several routes, but the customer should select one before the system displays the final instruction.
Keep rail events in child payment attempts. A customer may open a Bitcoin route, abandon it, then pay with USDC on Solana. Both attempts belong to the same invoice, but only one should satisfy it. This structure prevents abandoned destinations from becoming mysterious unmatched deposits and allows the platform to block or refund a second payment after the invoice is already paid.
Use quotes with clear validity rules
When the invoice is priced in fiat but paid with a volatile asset, generate a quote that records the asset amount, price source, timestamp, spread or fee treatment, rounding rule, and expiration. Do not recalculate the displayed amount silently while the customer is preparing a transaction. When the quote expires, let the user request a new one while continuing to monitor the old destination for late money.
Stablecoins can simplify the pricing step, but route-specific fees and token identity still matter. A token labeled USDC or USDT on an unsupported network should not satisfy the invoice. Store exact contract or mint identifiers and route version. The commercial amount can remain one dollar-denominated value while the settlement evidence records the precise units received.
Choose a destination strategy per chain
Bitcoin invoices commonly use a fresh address or payment request so an incoming output can be correlated reliably. Account-based chains may use a dedicated address, subaccount, smart-contract event, reference key, or transaction request. Reusing one destination for every invoice may be operationally convenient, but it requires a dependable reference and careful handling of identical amounts.
Expose the selected strategy as metadata. The client should know whether the instruction has an address, memo, reference, contract call, token account, or QR payload. Do not force all of these into a single string. Structured fields make validation easier and let wallets build a correct transaction without parsing display text.
Learn from chain-specific payment models
Bitcoin's unspent-output model means a payment can contain multiple outputs, and an invoice may be paid by more than one transaction. Ethereum token payments are typically identified through contract events and require attention to token contracts, transaction status, and log indexes. Solana payments may use transfer or transaction requests with references that help locate the matching transaction. The normalized API should preserve the evidence needed for each model.
The Bitcoin Developer Guide's payment-processing section provides a primary technical overview of receiving payments and is a useful reminder that pricing, orders, payment requests, validation, and confirmation are separate concerns. Apply the same separation even when another network offers different primitives.
Build a chain-aware observation layer
Each adapter should emit normalized observations: route, transaction identifier, sub-index, source, destination, asset, amount, block or slot reference, success state, first-seen time, and raw evidence pointer. The confirmation service then evaluates observations under a route-specific policy. This lets the invoice system stay independent from node vendors and indexer formats.
Use more than one recovery path. Real-time subscriptions or webhooks can update the checkout quickly, while periodic scans catch missed events. Deduplicate observations by a chain-appropriate settlement key. Keep reorganization or rollback handling explicit so a provisional detection can be withdrawn without deleting the original event.
Represent partial, excess, and late payments
An invoice can receive less than requested, more than requested, or several transfers that add up to the amount. Store each transfer and calculate the applied total using the invoice's pricing and tolerance policy. Avoid marking a payment complete merely because one transfer exists. For volatile assets, define whether multiple transfers use the original quote, their arrival-time value, or a manual resolution process.
Late payments should move into an exception workflow rather than disappearing. The platform may accept the original quote within a grace period, request an additional amount, issue a refund, or ask the merchant to decide. Make the policy visible before checkout and preserve the quote version that governed the instruction.
Publish reliable invoice webhooks
Events should describe durable facts such as invoice payment detected, payment confirmation advanced, invoice paid, invoice expired, payment held, refund initiated, and refund completed. Sign the raw event body, include a timestamp and event identifier, and support secret rotation. Merchants should deduplicate events and fetch the invoice when they need the latest aggregate state.
Do not emit “paid” before all conditions for merchant fulfillment are met. If the platform offers provisional acceptance, give it a different event and document the risk. Ordering can be difficult across chains and services, so include object versions and avoid promising global event order unless the infrastructure enforces it.
Design refunds and customer support together
A blockchain refund is a new payment. Confirm the destination through an authenticated flow instead of assuming the source address can receive funds. Exchanges and custodial wallets may require a fresh deposit address or memo. Let the refund specify the route, destination, amount, fee treatment, and reason, and require approvals appropriate to the value.
Support agents need a timeline that combines commercial events and chain evidence: invoice created, route selected, instruction shown, transaction observed, confirmations updated, policy decision, merchant webhook delivery, fulfillment, and refund. Mask sensitive fields but do not hide the data needed to explain why a visible transaction is still pending or why a wrong-network transfer cannot be automatically credited.
Reconcile merchant balances and treasury movement
Post balanced entries when a payment becomes recognized, when merchant funds become available, when platform fees accrue, and when assets are converted or paid out. Internal sweeps between wallets should never create merchant revenue. Store network and provider fees separately so the platform can compare route economics without changing the original invoice amount.
Reconcile the invoice database, ledger, custody records, and independent chain observations. Create queues for observed transfers without invoice application, paid invoices without balanced entries, custody movements without internal transfer records, and refunds without terminal settlement evidence. Aged exceptions are more useful than a single “all systems healthy” metric.
Offer capabilities instead of false uniformity
- Whether the route supports exact-amount requests, references, memos, or smart-contract calls.
- Whether partial and multiple payments can be combined automatically.
- How fees are paid and whether fee sponsorship is available.
- How confirmation confidence is calculated and exposed.
- Whether refunds can use the same asset and network.
- What happens to unsupported tokens or late transfers.
A capabilities endpoint lets clients adapt the checkout without hard-coding chain assumptions. Version it, because network support and provider behavior can change.
Conclusion
A practical crypto invoice API begins with one commercial invoice and many route-aware payment attempts. Use structured instructions, time-bound quotes, chain-specific settlement evidence, explicit confirmation policies, signed webhooks, authenticated refunds, and balanced ledger entries. That design gives merchants a consistent integration while preserving the facts needed to operate Bitcoin, Ethereum, Solana, and stablecoin routes safely.
