Crypto Gateway Integration Checklist

What do you build?

Four things, in this order.

Create a payment. Your server calls the provider with an amount, a currency and your order reference. It returns a payment identifier and either a hosted URL or an address plus a countdown.

Handle the callback. The provider calls your endpoint when payment state changes. This is where most of the real work is, and where most of the mistakes are.

Reconcile. Match settled amounts against orders on a schedule, independently of the callbacks. Callbacks are delivered over the network and networks lose things.

Handle exceptions. Underpayment, expiry, overpayment and wrong-network sends need a decision each. Deciding in production is how a support queue starts.

What does the webhook handler need?

Verify the signature before parsing anything. Every serious provider signs callbacks; treat an unsigned one as hostile traffic.

Be idempotent. The same event will arrive more than once, because retry logic exists on the provider’s side and delivery confirmation is imperfect. Key on the event identifier and make repeat processing a no-op rather than a second fulfilment.

Return 200 quickly and do the work afterwards. Handlers that fulfil orders synchronously inside the webhook time out under load, and a timeout looks to the provider like a failed delivery, so it retries, and now you have the previous problem at volume.

Never trust the amount in the callback without checking it against the order. Confirm the settled amount matches what you expected before releasing anything.

Which failure paths must you test?

Underpayment. Send about 2% less than the invoice. Providers differ enormously here and almost none document the behaviour. Some credit the partial amount, some hold pending a top-up, some require manual intervention. Decide what your shop does with a partially paid order before a customer creates one.

Late payment. Pay an invoice after it expires. The customer sent real money to a real address and your system has already timed the order out. What happens next is a policy question, and the provider’s default may not match your policy.

Wrong network. A customer sends the correct asset over a network you do not support, which the network guide covers in detail. Recovery ranges from automatic to impossible depending on the provider and the networks involved, and the answer belongs in your support documentation before it belongs in a ticket.

What do you check before going live?

That your test credentials and live credentials are different, and that nothing in your configuration silently falls back to test. That your webhook endpoint is reachable from the public internet and not behind an allowlist that a provider IP change will break. That you have a runbook for a payment that arrives without a matching order.

That somebody other than the person who built it can find the settlement report. This sounds trivial and is the single most common gap when the person who did the integration goes on holiday.

Where should you look next?

The developer API shortlist ranks providers on integration quality alone rather than on the overall weighted score. Accepting crypto payments covers the decisions that come before the code.

What to log, and what to log it against

Every payment event with its provider identifier, your order reference, the amount, and the timestamp you received it. That is the minimum that makes a discrepancy investigable a month later, and reconstructing it after the fact is expensive.

Log the raw callback body too, at least for a retention window. When a provider changes a field or you misread one, the original payload is the only thing that settles what actually happened.

The environment mistakes

Test and live credentials in the same configuration file, distinguished by a flag somebody can flip by accident. A webhook URL pointing at a staging host in production. An allowlist keyed to a provider IP that changes without notice.

All three are ordinary, all three fail quietly, and all three are caught by one deployment checklist that somebody actually reads.

Handing it over

Write down where the settlement report lives, who has access, and what the reconciliation job does. The person who built the integration understands all of it and will eventually not be the person answering a question about last quarter.

This sounds like process for its own sake and it is the single most common gap in small-team crypto integrations. The accounting guide covers what finance needs from the provider side.

Before you switch traffic

Run the three live tests from the testing guide, confirm the reconciliation job runs on schedule and reports somewhere visible, and send one real payment through the production path end to end.

Where to go next

The webhook guide covers the handler in depth, since that is where most of the real work sits. The testing guide covers the live checks before launch, and the developer API shortlist ranks providers on documentation and API quality rather than overall score.

What to do about provider changes

Providers change API fields, add required parameters and deprecate endpoints, usually with notice that arrives by email to whoever registered the account. That is frequently not the person maintaining the integration.

Make sure the technical contact is a role address rather than an individual, and that somebody reads it. Then keep the raw callback payloads for a retention window, so when a field changes shape you can see exactly what arrived rather than inferring it.

This is unglamorous and it is the difference between a scheduled hour of work and an outage discovered by a customer.