How to Integrate a Crypto Payment API: A Developer Guide

Accepting crypto payments is no longer a weekend project. The payment logic itself — create a session, redirect, confirm — is straightforward. What trips up most integrations is everything around it: webhook reliability, settlement mechanics, and the compliance layer that regulators now require. This guide walks through each step at a practical level, including what a well-designed API should handle invisibly on your behalf.

---

1. Choosing a Crypto Payment API

Not all crypto payment APIs are equivalent. Before you write a single line of code, evaluate the provider on these criteria.

REST vs. SDK. A REST API is portable across stacks and easier to audit. SDKs speed up integration but add a dependency you need to maintain. A good provider offers both: a clean REST interface as the canonical layer, with SDKs as thin convenience wrappers over it. If the SDK hides important response fields or error codes, treat that as a warning sign.

Webhook reliability. The payment confirmation flow depends entirely on webhooks being delivered. Check whether the provider publishes an SLA for webhook delivery, retries on non-2xx responses, and provides a delivery log you can inspect during development. An API that fires a webhook once and forgets it is not production-ready.

Supported currencies and settlement. Determine which cryptocurrencies are accepted — typically Bitcoin, Ether, and major stablecoins — and critically, how settlement works. For most European merchants, settling in EUR (euros) automatically eliminates crypto price risk without requiring you to manage exchange operations. Look for providers that handle conversion and wire EUR directly to your bank account.

Regulatory authorisation. This is the item most developers skip and later regret. In Europe, a crypto payment service provider must hold authorisation under MiCA (Markets in Crypto-Assets Regulation) or, in Switzerland, operate under AMLA (Anti-Money Laundering Act) supervision via a self-regulatory organisation such as SO-FIT. If a provider cannot show you their authorisation, the compliance burden — and the legal exposure — shifts to you. WickiePay is SO-FIT regulated and MiCA-ready; the compliance work is built into the API, not delegated to your integration.

---

2. Core Integration Steps

The fundamental pattern for a crypto payment integration is a four-step sequence.

Step 1 — Create a checkout session. Your server makes a POST request to the checkout endpoint with the order amount, currency, a reference ID from your system, and the URL to redirect the customer to after payment.

POST /v1/checkout
{
  "amount": "149.00",
  "currency": "EUR",
  "reference": "order_8821",
  "redirect_url": "https://yourstore.com/orders/8821/confirmation"
}

The response includes a session_id and a payment_address — the address the customer sends crypto to — along with a checkout_url you can redirect to directly.

Step 2 — Redirect the customer or embed the widget. For most integrations, redirecting to the checkout_url is the fastest path. The provider's hosted page handles currency display, QR code generation, and payment timer UX. If you need deeper control, an embeddable widget is available, but redirect-first keeps your PCI and compliance surface small.

Step 3 — Listen for the webhook. Your server receives a payment.confirmed event at the callback URL registered in your account settings. This is the signal to act on — it means the incoming transaction has been validated and passed the provider's compliance checks. More on the distinction between "confirmed" and "settled" in the next section.

Step 4 — Credit the order in your system. On receipt of a verified payment.confirmed webhook, mark the order as paid, trigger fulfilment, and return HTTP 200 to acknowledge. If your handler returns anything other than a 2xx, the provider will retry.

Keep your checkout session creation on the server side. Never expose API keys in client-side JavaScript.

---

3. Webhooks and Payment Confirmation

Webhooks are where most integration bugs appear, so this section is worth reading carefully.

Signature verification. Every webhook payload should include a signature header computed from the request body using HMAC-SHA256 and your webhook secret. Verify this signature before processing any event. Skipping this step means anyone who knows your callback URL can fake payment confirmations.

const expectedSig = crypto
  .createHmac('sha256', process.env.WEBHOOK_SECRET)
  .update(rawBody)
  .digest('hex');

if (expectedSig !== req.headers['x-wickiepay-signature']) {
  return res.status(401).end();
}

Idempotency. Webhooks are delivered at least once, which means your handler may receive the same event more than once. Store the event_id from the payload and check for duplicates before crediting an order. A simple check against a processed-events table is sufficient.

payment.confirmed is not the same as funds received. When the webhook fires, the transaction has been validated and cleared compliance screening. Settlement to your EUR bank account happens on the next business-day batch run (or faster, depending on your plan). Do not gate EUR payout logic on the webhook — gate order fulfilment on it, and let the provider handle the conversion timing.

Retry logic. If your endpoint is temporarily unavailable, the provider will retry with exponential backoff over several hours. Ensure your handler is idempotent so catching up on a retry queue does not double-credit orders.

---

4. Compliance — What the API Handles for You

This section covers the part of crypto payment integration that most developer guides omit entirely.

Under current EU and Swiss AML rules, accepting crypto payments above certain thresholds triggers mandatory compliance checks. This includes Know Your Customer (KYC) identity verification, Anti-Money Laundering (AML) screening, the Travel Rule (which requires originator and beneficiary information on every crypto transfer — no minimum threshold), and real-time sanctions screening against EU, UN, OFAC, and SECO lists.

A regulated payment API absorbs all of this. When a transaction passes through WickiePay, the compliance pipeline runs automatically per transaction:

• KYC/AML checks are executed before funds are released.
• Travel Rule data collection and transmission to counterparty VASPs (Virtual Asset Service Providers) is handled by the API for qualifying transfers.
• Sanctions screening runs in real time against current consolidated lists.

From your integration's perspective, a payment.confirmed event means the transaction has already cleared compliance. You do not implement any of this logic in your code. If a transaction is blocked by compliance checks, the customer receives a response through the provider's interface, and you receive a payment.failed event with a reason code rather than a payment.confirmed.

This is the practical consequence of choosing a regulated provider: your integration is shorter, your legal exposure is smaller, and you do not need to become an AML specialist to accept crypto commercially.

---

Frequently Asked Questions

Which cryptocurrencies does the API support?

WickiePay accepts Bitcoin (BTC), Ether (ETH), and USDC and USDT stablecoins. EUR settlement applies to all of them — incoming crypto is converted automatically, so nothing sits on your balance sheet as a crypto asset.

Is there a test environment for development?

Yes. A free trial account gives you access to the full API in test mode, including webhook delivery, signature verification, and simulated compliance flows. Sign up at /contact. Test-mode transactions do not move real funds but the API responses are structurally identical to production, so the same integration code works in both environments.

Are there rate limits, and how do retries work?

The API applies standard rate limiting at the checkout session creation endpoint. Webhook delivery retries are managed by the provider and follow exponential backoff for failed deliveries. Your callback endpoint should respond within five seconds; long-running order logic should be handled asynchronously after you return the HTTP 200 acknowledgement. Specific rate limit thresholds are documented in the developer reference.

---

Ready to Integrate?

WickiePay provides a REST API, webhooks, and EUR auto-settlement under SO-FIT regulation and MiCA-ready compliance infrastructure. Request a free trial account and API credentials at /contact.