Crypto Invoicing: The Complete Payment Lifecycle Guide

Crypto invoicing links an order to a monitored blockchain payment. The invoice binds a merchant order identifier to an expected amount, an expiry, valid asset-and-network choices, payment status, and the resulting transaction record. It is the transaction record behind each Paymos payment surface.

A wallet address alone cannot do that job. It does not identify the order, decide when the payment is final, or tell the merchant system when fulfillment is safe. The invoice supplies that missing commercial context. For the wider model, read how crypto payments work.

What information does a crypto invoice need?

A production invoice answers three questions. What does the customer owe, where can they pay, and how will the merchant match the transfer to an order? At minimum, store the merchant's order identifier, requested amount, pricing currency, expiry, selected asset and network, destination address, invoice status, and blockchain transaction reference.

Keep the asset and network together in every customer-facing label. “USDT” alone is incomplete because USDT on Tron and USDT on Ethereum are separate on-chain assets. The payment instructions should also expose a QR code or copyable address, the exact token amount, and a live status. The merchant record should retain both its own order ID and the processor's invoice ID so support and reconciliation can trace either side of the transaction.

How should invoice creation prevent duplicates?

Invoice creation must be idempotent at the business-order level. A timeout can leave the merchant unsure whether the first request succeeded, and retrying without a stable identifier can create two payable invoices for one order.

Paymos uses the caller-supplied external_order_id for this purpose. Reusing the same external order identifier returns the existing invoice instead of creating another one. Paymos does not use an Idempotency-Key header for invoice creation, so the integration should generate and persist the order ID before its first API call.

Store the returned Paymos invoice ID with the original order. If the response is lost, repeat the request with the same external_order_id, then continue with the existing invoice. This is safer than generating a new identifier after every transport error.

How does the customer receive payment details?

The customer needs one unambiguous payment route before the wallet sends the payment. Paymos can present it through Hosted Checkout, an embedded iframe, a Payment Link, the Widget SDK, a CMS plugin, or a custom interface backed by the REST API. The route should show the selected asset, network, amount, address, QR code, and current status.

Hosted Checkout handles the payment interface. The merchant keeps ownership of the order and fulfillment logic. A CMS plugin connects the same invoice model to a supported commerce or billing platform. The REST API fits teams that need a custom interface, but it also makes them responsible for validation, error handling, signed requests, status presentation, and reconciliation. Choose the least custom surface that still meets the product experience requirement.

What is the complete Paymos invoice lifecycle?

The integration surface changes, but the control loop stays the same:

1. Create the invoice with a stable external_order_id.
2. Present an available asset-and-network route through checkout, a link, a plugin, a widget, or a custom interface.
3. Let the payer's wallet send the payment and cover the inbound network fee.
4. Wait while Paymos applies the confirmation policy for that network and amount.
5. Apply the project's underpayment tolerance to the amount actually received.
6. Verify and durably record signed webhook delivery before running fulfillment.
7. Reconcile the order ID, Paymos invoice ID, received amount, and blockchain transaction reference.

This sequence shows where duplicate prevention, finality, underpayment, and fulfillment controls belong across every supported integration surface. The exact request shape depends on the chosen surface. Teams implementing a custom path can pair it with the REST API payment guide.

When is a detected payment safe to fulfill?

Detection is not finality. A processor can observe a transaction before the network has given enough confidence that it will remain in the canonical history. The invoice should move to a fulfillment-ready state only after the applicable confirmation policy has completed.

Paymos sets confirmation policy by both network and payment amount. Smaller payments can require fewer confirmations, while larger payments can wait for a stronger threshold. There is no single confirmation time that applies to every invoice. Network conditions also change the elapsed time.

Fulfill only from the final paid state. Never rely on a wallet screenshot, customer-supplied transaction hash, or early “seen” event. The blockchain confirmations guide explains why the required depth varies.

How does underpayment tolerance work?

Underpayment follows a project-level percentage. It does not depend on an ad hoc support decision. The default Paymos policy is strict matching with 0% tolerance. If the amount received falls within the configured tolerance, the invoice completes and the merchant settles the amount paid. Paymos does not add the missing amount.

If a single-payment invoice falls below the tolerance threshold, it remains underpaid. If the invoice allows multiple payments, it can remain open while the payer sends the remainder. The integration should display that state instead of silently marking the order paid.

Set tolerance from the economics of the order. A small percentage may absorb wallet rounding without creating manual work, but a broad tolerance can turn a pricing error into an accepted discount on every invoice.

How should signed invoice webhooks be processed?

Webhooks move invoice state into the merchant system. Paymos signs them with HMAC-SHA256 in the X-Webhook-Signature header using the format t={timestamp},v1={hmac_hex}. The receiving service should verify the timestamp and signature with a timing-safe comparison before parsing the event as trusted data.

Delivery is retryable, so handlers must be idempotent. A Paymos delivery cycle makes 11 total attempts—one initial attempt and ten retries—over approximately 16 hours. Failed or undeliverable events can be replayed manually.

Return success only after the event has been durably recorded. Then process fulfillment from that record. If downstream work fails, retry it internally instead of asking the webhook sender to repeat an event whose receipt was already stored.

X-Webhook-Signature: t=1785326400,v1=2b4f...
Content-Type: application/json

What should reconciliation store?

Reconciliation should create one complete trace. Connect the commercial order, processor record, and blockchain transaction. Store the external order ID, Paymos invoice ID, requested and received amounts, asset, network, transaction reference, final state, and relevant timestamps. Keep the merchant-defined processing key used to prevent duplicate work.

Reconcile from processor state rather than from a customer-supplied transaction hash. A transfer can use the wrong asset, wrong network, wrong address, or insufficient amount while still looking plausible in a block explorer. The invoice state evaluates the transfer against the payment request.

Support should find the record through three identifiers. Order ID, invoice ID, and transaction reference should all reach the same trace. That reduces refund errors and gives the merchant a defensible audit trail when a customer disputes fulfillment.

Which crypto invoicing route should you choose?

Use a Payment Link for occasional manual invoices. It fits billing through sales or support. Use Hosted Checkout or the embedded flow when a website needs a complete payment page without owning every wallet interaction. Use an official CMS plugin when the store runs on one of Paymos's supported platforms.

Choose the REST API for a genuinely custom workflow. Paymos separates Sandbox and Production credentials but keeps the same API surface, so teams can test invoice outcomes and webhook handling before moving real funds. Payment and Payout credentials remain separate.

Keep the same control loop for every route. Create with a stable external order ID, present exact payment details, wait for the final paid state, verify signed webhooks, and reconcile before fulfillment.