Crypto payments API: how it works
A crypto payments API enables your backend to create a payment request, show the customer where to pay, and find out when the funds have arrived, without running your own blockchain nodes. A payment goes through five stages: invoicing, payment, network confirmation, webhook and reconciliation. Most errors lie in the last two stages: duplicate webhooks, unsigned notifications, and payments that arrive incomplete, in excess, or late. The guide traces the lifecycle using generic pseudocode, then covers webhook security, edge cases and a pre-production checklist.
The lifecycle of a crypto payments API: from invoice to reconciliation
Vendors use different terminology, but the lifecycle is the same across the board.
| Stage | What happens | What your system does |
|---|---|---|
| 1. Invoice | Call the API with the amount, asset, network and order ID. The provider returns a payment address or link. | Save the invoice ID alongside the order and set an expiry date. |
| 2. Payment | The customer sends the funds. | Display the asset, network, address, exact amount and a countdown timer. |
| 3. Network confirmation | The transaction is included in blocks, and the supplier waits for the required number of confirmations. | Keep the order on hold and do not dispatch the goods. |
| 4. Webhook | The supplier notifies your endpoint of a status change. | Verify the signature, remove duplicates, update the order. |
| 5. Reconciliation | Compare the supplier’s records with your own. | Match by invoice ID, flag discrepancies, verify the settled amount. |

Invoice creation
The request contains the information the provider needs to construct the payment instruction. Below is generic pseudocode, not the endpoints of any actual provider:
POST /invoices
Idempotency-Key: order-1042-attempt-1
{
‘order_id’: ‘1042’,
‘amount’: ‘150.00’,
‘asset’: ‘USDC’,
‘network’: ‘polygon’,
‘expires_in’: 1800
}
-> 201
{
“invoice_id”: ‘inv_abc123’,
‘address’: ‘0x...’,
“status”: ‘pending’
}Display the network next to the address on the payment page. The same token exists on multiple blockchains, and a transfer to the wrong network may never arrive. The Bitcoin developer documentation recommends a separate address for each payment request, as this means you only need to track which request uses which address. Most providers do this automatically, with a unique address or link for each invoice.
Confirmation and ‘paid’ status
A transaction appearing on the network does not yet constitute a paid invoice. The same documentation states that a payment with zero confirmations is not secure without a risk assessment, and for high-value payments it recommends waiting for at least six confirmations. The supplier sets its own policy for each network, so this must be read, and goods are only delivered once the status reaches the level the supplier defines as final.
Webhooks, idempotence and edge cases
Check every webhook
Webhooks are the part of the crypto payment flow that an attacker can access, as they are simply HTTP requests to your public endpoint. Anyone who finds the URL can send a fake “payment confirmed” message. That is why the security of a payments API starts with signatures.
Most providers sign the request body with a shared secret. The standard method is HMAC, which RFC 2104 describes as a message authentication mechanism, based on cryptographic hash functions combined with a shared secret key. The exact name of the header and the schema vary from one provider to another, so please refer to their documentation. Generic pseudocode for the handler:
function handleWebhook(request):
raw = request.rawBody # raw bytes, not parsed JSON
expected = hmac(secret, raw)
if not constantTimeEquals(expected, request.signature):
return 401
event = parse(raw)
begin transaction
# the `event_id` column has a UNIQUE constraint
if not insertEventId(event.id):
rollback
return 200 # duplicate delivery
# lock the order row, then apply the change
order = selectForUpdate(event.invoice_id)
applyStatus(order, event.status, event.amount)
commit
return 200
ALLOWED = {
‘pending’: [‘confirming’, ‘expired’],
‘confirming’: [‘paid’, ‘underpaid’],
‘underpaid’: [‘paid’],
“paid”: [],
‘expired’: []
}
function applyStatus(order, newStatus, amount):
if newStatus == order.status:
return # nothing to change
if newStatus not in ALLOWED[order.status]:
log(‘ignored out-of-order event’, order.id, newStatus)
return # never move backwards
order.status = newStatus
order.save()Two details make this code safe under load. Firstly, the event ID is recorded via an insert protected by a uniqueness constraint, not via a separate seen()-type check: with a pre-transaction check, two parallel transactions might both find that the event does not exist and might both modify the order. Secondly, `applyStatus` only accepts transitions from `ALLOWED`, so a late-arriving ‘confirming’ event cannot reverse an order that has already been paid. Adapt the state machine to the supplier’s actual statuses, and if the supplier can skip a stage, explicitly allow that skip.

A few rules ensure security. Keep the secret separate from the code and change it whenever someone who has had access to it leaves. Serve the endpoint only via HTTPS. If the provider includes a timestamp in the signed data, reject requests that are too old. For orders with a real-world value, confirm the status via an API call before delivery, so that a leaked secret cannot trigger delivery on its own.
Idempotence and retries
Be prepared for the situation where the same event arrives twice or events arrive in a different order. Providers usually retry delivery when the endpoint does not respond, so a slow server can produce duplicates, and the handler must update the status only once. As in the pseudocode above, this requires an atomic insert of the event ID, written within the same transaction as the status update. For events arriving in a different order, check the transition before applying it. An ignored event remains in the log, and the reconciliation process subsequently compares the order with the supplier’s record.
Idempotence also matters in the opposite direction. A POST request is not idempotent by default, so if the call to create the invoice times out, a blind retry may create a second invoice for the same order. The IETF’s Idempotency-Key draft describes a header that allows the server to recognise retries of the same request, thereby making the POST to be fault-tolerant. The document is still an Internet Draft, i.e. a work in progress, and not all providers accept the header, so check whether yours does and what key format it expects. Construct the key from the request ID, so that a retry reuses it each time.
What no network can guarantee: the two-general problem
The rule of expecting duplicate deliveries has a theoretical explanation that vendors’ documentation usually fails to mention. In 1975, E. A. Akkoyunlu, K. Ekanadham and R. V. Huber described, in a paper on communication in computer networks, a problem that Jim Gray popularised in 1978, in his notes on database systems, under the name of the two-generals problem. Two armies positioned on different hills must attack simultaneously, and the only means of communication is a messenger who may be captured en route. No matter how many acknowledgements they send to one another, neither general can be certain that the last message has arrived, and the formal result is that, on a channel prone to message loss, no protocol can guarantee agreement with certainty.
The payment webhook replicates this situation exactly. The provider sends the notification, the endpoint processes it, and the 200 response may be lost en route. From the provider’s perspective, the notification appears undelivered, so it resends it. It follows that ‘exactly once’ delivery cannot be guaranteed by the network, and real-world systems opt for ‘at least once’ delivery, combined with an idempotent receiver, which treats the second arrival of the same event as a no-op. The atomic insertion of the event ID in the pseudocode above is the engineering response to a proven impossibility.
The fake webhook relates to a related problem, formulated in 1982 by Leslie Lamport, Robert Shostak and Marshall Pease in ACM Transactions on Programming Languages and Systems, known as the Byzantine Generals’ Problem. Here, the difficulty stems from participants who lie, whilst lost messages take a back seat. Their key finding shows that, when messages are merely ‘verbal’, consensus requires more than two-thirds of the participants to be honest, whilst signed messages—which cannot be forged—make the problem solvable under much broader conditions. HMAC verification applies the same idea on a small scale: a message that does not bear the correct signature is treated as coming from a disloyal participant.
The analogy has limitations that are worth noting. The Two Generals’ Problem is a result concerning certainty, not probability, and in practice networks deliver almost all messages, so duplicates are rare, even if inevitable. More importantly, an HMAC calculated using a shared secret differs from the digital signature in the Byzantine model. Both parties hold the secret, so either of them can produce a valid message, and the provider cannot prove to a third party that it, and not the merchant, sent a particular notification. In the event of a dispute, the source of truth remains the provider’s log, queried via the API, and the reconciliation described below is where this source is cross-checked against the merchant’s own database.
Seamless secret rotation
The recommendation to change the secret when someone who had access to it leaves raises a practical problem that is rarely addressed in documentation. If the old secret is replaced abruptly, webhooks already in the provider’s retry queue, signed with the old key, will be rejected, and the relevant requests will remain blocked. The usual solution is an overlap window, during which the handler accepts signatures calculated using either of the two secrets, followed by the permanent withdrawal of the old one once the window has expired.
Some providers allow two secrets to be configured simultaneously precisely for this scenario, whilst others do not; it is worth finding out the difference before integration. In both cases, the rotation procedure should be written and tested once, in the test environment, because the moment it is needed – for example, following a data breach – is the least suitable time for improvisation.
Incomplete payments, overpayments and expired invoices
Crypto payments often arrive with a slightly different amount, so the statuses ‘paid’ and ‘unpaid’ are not sufficient.
| Scenario | What happened | Standard handling |
|---|---|---|
| Incomplete payment | Less than the requested amount has arrived, often because the payer’s exchange has deducted a withdrawal fee. | Do not dispatch automatically. Apply a tolerance rule or send the case for manual review and show the customer the difference. |
| Overpayment | More than the requested amount has been received. | Dispatch if the order total is covered, then decide whether to refund the difference or credit it. |
| Invoice expired | The invoice period expired before payment was made, or payment was received after the expiry date. | Do not dispatch against the old invoice. Check the exchange rate and either fulfil the order, reissue the quote, or refund the money.</ td> |
| Wrong network or asset | The customer sent the correct token to the wrong blockchain or sent a different token. | The supplier’s assistance is often required, and recovery is not guaranteed. |
The exact statuses and fields depend on the provider, so they must be mapped out before writing the business logic.
Hypothetical example: the invoice is for 200 USDC, the buyer’s exchange withholds 1 USDC, and 199 USDC arrives. A rule such as “we accept a difference of up to 2 USDC, and any larger difference goes to manual verification” reduces the number of support tickets. Write the rule in your terms and conditions, specifying who bears the network fees.
Refunds require careful handling, as a confirmed crypto transaction cannot be reversed, and a refund is a new transfer sent by you. The Bitcoin documentation describes returning funds to the original address as “very unsafe”, as a payment from a multi-user wallet may originate from an address over which the customer has no control. Instead, ask the customer for a refund address.
Testing and pre-production checklist
Before choosing a provider, read their documentation alongside the lifecycle outlined above. Inqud has a dedicated page for crypto payments API, which provides a concrete benchmark for comparison.
Ask whether the provider has a test environment. If not, make real payments with minimal amounts. Before going live, check the following:
- Creating an invoice twice with the same idempotency key returns a single invoice. This test only applies if the provider accepts the Idempotency-Key header: support depends on the provider, and the header is currently only described in an IETF Internet-Draft. If the provider does not support it, test your own deduplication based on the order ID.
- A webhook with a valid signature changes the order status.
- A webhook with an invalid signature or no signature is rejected with an error and does not change anything.
- The same webhook delivered twice changes the status only once.
- Events arriving in a different order do not revert an order.
- Incomplete payments, overpayments and expired invoices each follow the specified rules.
- A payment made via the wrong network is visible to the support team, and the message to the customer is clear.
- The reconciliation process detects a mismatched entry that has been intentionally submitted.
- Logs contain event and invoice IDs, but never secrets.
- The payment stage to the merchant or the conversion stage reaches the bank account or wallet with the expected amount.
Reconciliation as the third source of truth
The guide treats reconciliation as the safety net for the flow, and its role becomes clearer when viewed through the lens of accounting. The merchant has two records of the same payment: their own database, updated via webhooks, and the provider’s record, accessible via API. In crypto payments, however, there is also a third source, independent of both: the transaction itself, publicly visible on the blockchain, with its identifier, the amount transferred, the destination address and the number of confirmations.
A well-designed reconciliation process compares the three sources and treats any discrepancy as a case requiring verification. An order marked as paid without a corresponding transaction on the blockchain indicates a fake webhook or a logic error. A confirmed transaction without an updated order indicates a missed webhook. A discrepancy in the amount between the provider and the blockchain indicates an unreported fee or an unexpected currency conversion. The frequency of reconciliation depends on volume: daily for most small merchants, every few hours for high volumes, with a documented tolerance for rounding differences.
The advantage of the third source is that it does not rely on trust in either party. Its limitation is that a blockchain explorer shows what has been transferred between addresses, without revealing who owns an address, so the link between the transaction and the order remains the one created by the provider via the unique invoice address.
Common mistakes
- Trusting unsigned webhooks. A public endpoint without signature verification allows anyone to mark an order as paid.
- Delivering on the first notification. An early ‘pending’ or unconfirmed status is not final. Only fulfil when the status is documented by the provider as settled.
- A handler that is not idempotent. A retry or duplicate event delivers the order twice, so record each event ID under a uniqueness constraint and update the status in the same transaction.
- Relying exclusively on webhooks. A failed delivery leaves an order stuck. Run a reconciliation process that compares the provider’s records with your orders.
- Refund to the sender’s address. A payment from an exchange or a shared wallet may come from an address to which the customer has no access. Request a refund address.
Before integration: who, legally, is the provider
The checklist above tests the code, but assumes that the chosen provider is authorised to offer the service in your market. For firms selling to customers in the European Union, the question has had a clear answer since this year. The transition period provided for by the MiCA Regulation, under which providers previously registered under national regimes could continue their activities, ended on 1 July 2026. From that date, any entity offering crypto-asset services to EU clients without authorisation as a crypto-asset service provider (CASP) is in breach of European law and must cease its activities.
The European Securities and Markets Authority (ESMA) publishes the interim MiCA register, which lists authorised providers, and explicitly advises clients to check this register to ensure their provider is authorised. Following the first post-deadline update, published in early July 2026, the register contained 280 CASPs. For a trader, the check takes a few minutes and should be carried out before writing a single line of code, as integration with an unauthorised provider could be disrupted overnight, should that provider enter into liquidation.
The legal status of each provider, including the one mentioned in this article, must be confirmed directly in the official register and in the contractual documents. The reason is that authorisations cover specific services, and a provider may be authorised for transfers and custody without being authorised for other activities. For non-EU traders, the framework varies from one jurisdiction to another, and verification must be carried out with the relevant national authority.
Specifically, the entry in the ESMA register indicates the authority that granted the authorisation, the home Member State, the entity’s LEI identifier and the services for which it is authorised. It is useful to compare this information with that in the proposed contract: the name of the legal entity signing the contract, the services it will actually provide, and the country in which clients’ funds will be held. Any discrepancy between the entity listed in the register and that in the contract – which is common in groups with multiple subsidiaries – should be clarified in writing before signing.
Where to find providers and what a listing confirms
The shortlist of providers is usually drawn from the top search results and recommendations from other developers, and the systematic comparison proposed by this guide involves more options than a paid search provides. The online payments category in the Jasmine Directory groups together payment processors, gateways and infrastructure providers, with an editorial description that also covers web standards for payments, such as the Payment Request API developed by the W3C.</ p>
On the regulatory side, the financial services category includes payment processors and fintech firms, and its description recommends consulting the official registers maintained by national authorities. A listing confirms that the firm exists, that it operates in the stated field and that it can be contacted using the same contact details. It does not verify MiCA authorisation, does not test API security and does not constitute a recommendation; for authorisation, the relevant source remains the ESMA register.
The business side and the role of an accelerator
Why merchants are adding crypto payments
Product and finance teams usually have practical reasons for accepting crypto, i.e. accepting crypto payments: customers from abroad who prefer to pay in stablecoins, settlement outside bank opening hours, and the absence of forced chargebacks, which are specific to cards. The trade-offs are also very real. The prices of assets such as BTC and ETH fluctuate between the time an invoice is issued and the time of payment, whilst stablecoins reduce this risk without eliminating it, as you remain dependent on the issuer. Rules for suppliers, taxes and reporting depend on the jurisdiction. The information provided here is of a general nature and does not constitute legal or tax advice.
The diversity of payment methods also carries an organisational cost. An analysis on the Jasmine blog about payment diversification, from crypto to BNPL and biometric payments notes that many merchants stop at displaying a message such as ‘we accept Bitcoin’, without implementing the processes behind it. This guide describes precisely these processes, and their cost – in terms of development, testing and support – should be weighed up against the actual volume of payments that the new method will generate. An honest estimate starts with the question of how many existing customers have actually requested this option in the last year.
How an accelerator saves weeks of integration time
What follows describes a model of cooperation, not a signed agreement. Building a payment flow like the one above takes weeks, once you factor in signatures, retries, reconciliation and testing. An accelerator can offer projects in its portfolio a ready-made integration, so that a young team does not have to spend entire sprints on payments.
One example is Inqud, a crypto payments platform for businesses, which covers crypto payment acceptance, conversion, payments to third parties, on-ramp and off-ramp, and has an OTC desk. Teams can connect via an API, an iFrame widget or a hosted payment page, and according to the company, integration takes around two days. KYB verification is a separate stage, the duration of which is not covered here. Accepted assets include BTC, ETH, USDT and USDC, on networks such as Tron, Bitcoin, Solana, Optimism, Arbitrum and Polygon, and funds received can be automatically converted into the chosen currency. Teams wishing to have their own interface can use the SDK, and an MCP server provides the API documentation.
In a partnership of this kind, each party stands to gain something tangible:
- The accelerator adds value to its portfolio without having to build its own payments product.
- Start-ups receive payments infrastructure from day one. According to the company’s description, there is no monthly subscription fee; the commission is charged per transaction; high-volume users may be offered individual rates; and payments between participants within the system are commission-free.
- The platform gains access to an ecosystem of emerging products and direct feedback from the teams using it.
The terms and conditions for a specific accelerator programme are not covered in this article.
Frequently Asked Questions
What does a crypto payments API do?
It allows the backend to create a payment request for an order, returns an address or a link for the customer, and reports status changes as the payment passes through the network. Many providers also handle currency conversion and payments to third parties. Your code remains focused on orders, whilst the provider handles the blockchain side.
