Accept crypto payments

Four HTTP calls and one webhook. We handle the crypto, the exchange, and the on-chain waiting — you get a USD-denominated payment link and a signed event when it lands.

How it works

1. 1You call

   POST a USD amount to /api/crypto/deposits. We return a hosted payment link.

2. 2Customer pays

   On the payment page they pick a coin + network and send crypto from any wallet.

3. 3We confirm

   We watch the chain. Once confirmed, funds are credited to your balance.

4. 4We notify

   A signed deposit.completed webhook hits your server with the metadata you set.

Glossary

Deposit

One payment. Address + USD amount + 60-minute window.

Invoice

Shareable payment link (a payment intent). A deposit is created when the customer picks a coin + network.

Payment token

Public id (pay_…) in the checkout URL. Safe to share.

Webhook

Signed POST we send when payment state changes. Skips polling.

Test mode

Keys prefixed ecp_test_. No real crypto, no balance impact.

Idempotency key

Optional header. Same key + body within 24h returns the cached response.

1. Create a payment

POST a USD amount. We return a hosted checkout link — the customer picks their coin + network there.

Response:

This is a payment intent — a paymentToken and hosted link, not an on-chain address yet. In production you redirect the customer to paymentLink and they pick a coin. Payment links live 7 days; once a currency is selected a deposit is created and the clock shortens to the 60-minute deposit window.

2. Select a coin + network

The hosted /pay page does this when the customer chooses a currency — it materialises the deposit (address + exact crypto amount) and returns a depositId. Call it directly for a headless checkout, or to drive this test loop to completion. (No API key needed — the payment token is the authorization.)

3. Complete the deposit (test mode)

Test deposits never reach an exchange. POST the depositId from step 2 here to drive it to completed — this fires the full deposit.confirming → deposit.completed webhook sequence. (A paymentToken also works once a deposit exists; calling it before step 2 returns 409 NO_DEPOSIT_YET.)

4. Handle the webhook

Set a webhook URL in API & Webhooks. On completion we POST a signed event — verify it, then update your order.

Next steps

• Free vs Pro — what each plan unlocks at the API level.
• API reference — every endpoint with full parameters and responses.
• Embed checkout — render the checkout inline on your own site (Pro).
• Webhooks — event types, retry cadence, signature verification.
• Node.js SDK — skip the HTTP + HMAC boilerplate.

Embedded checkout vs the hosted link

Both plans can mint payment tokens and redirect customers to /pay/<token> — that hosted page is the universal checkout. Pro adds the ability to render that checkout inside an iframe directly on your own site via embed.js, so customers never leave your domain. See Embed checkout below for the full integration.

Endpoint index

Every Bearer-API-key endpoint at a glance. Detail sections follow below; the public /api/pay/* checkout endpoints and the full schemas live in the OpenAPI spec.

Create a deposit

Create a new deposit session. Returns a unique payment address plus a hosted checkout link you can redirect your customer to. The deposit expires 60 minutes after creation.

Request

Response

Get deposit status

Poll a deposit to check its current state. We recommend a 5-second polling interval — or skip polling entirely and use webhooks.

Path parameters

Request

Response

Complete a test deposit

Test-mode deposits never reach a real exchange. This endpoint drives a sandbox deposit to completed immediately and fires the full webhook sequence exactly as production would.

Path parameters

Request

Response

Test-mode completions fire the same events (deposit.confirming then deposit.completed) with isTest: true in the payload so you can filter in your handler. Test deposits are excluded from your balance and volume rollups, so they never affect billing.

Create an invoice

Invoices are shareable payment requests. Create one, and we give you a hosted checkout link you can email the customer — or we can email it for you.

Request

Response

Get an invoice

Fetch a single invoice by its id or its paymentToken (same as /check). Returns the same object as Create an invoice (every field dual-emitted in both camelCase and snake_case), plus email_status, paid_at, and expires_at. A test-mode key resolves only test invoices; a live key only live ones — mismatches return 404.

List payments

List deposits for your business. Supports filtering by status and currency, plus pagination. Includes aggregate stats across the full result set.

Query parameters

Request

Response

Get a payment

Fetch a single deposit by its id or its paymentToken — the same row shape as List payments, plus an autoConvert sub-object (Pro). For a lighter status check, prefer /check; this endpoint returns the full record. Same test/live visibility rule as the list.

Get balance

Current balance plus lifetime volume, fees collected, and pending deposit count. Useful for dashboards, billing reconciliation, and webhook-independent polling.

Request

Response

List customers

Everyone who has paid you, with lifetime totals and their five most recent transactions. Filter by status, search by email or name, and paginate with limit + offset. Rows are dual-emitted (camelCase + snake_case). A test key sees test transactions; a live key sees live ones.

Query parameters

Request

Response

List currencies

Returns the currencies your connected exchange supports, each with available blockchain networks, minimum confirmations, and current USD pricing. Use this to populate a currency picker or validate user input before creating a deposit.

Request

Response

Setting up

Add a webhook URL in API & Webhooks. A signing secret is auto-generated on first save — use it to verify signatures, rotate any time.

Events

Payload shape

All webhook bodies share the same envelope: an event string and a data object matching the event type.

Signature header

Every request includes an X-ECP-Signature header. Stripe-style comma-separated key/value pairs:

t is the Unix timestamp when we signed the request. v1 is HMAC-SHA256 of `${t}.${rawBody}` using your webhook secret, hex-encoded.

Signature verification

Reject any request where the signature doesn't match — anyone who knows your endpoint URL could otherwise spoof payments. Reject requests where abs(now - t) > 300 seconds to defeat replays.

Node.js

The official SDK handles this for you:

Python

PHP

Retries & replay

Endpoint is down for maintenance? Don't worry. We retry automatically with exponential backoff, persist every attempt, and give you a manual replay button so nothing ever slips through the cracks.

What triggers a retry

• HTTP response outside 2xx (e.g., 500, 502, 503).
• Request timeout — we wait up to 10 seconds for a response.
• Connection refused or DNS failure.

Retry schedule

Total window: ~7 hours across 6 attempts. Each delay carries up to ±20% random jitter, so the exact timing varies slightly from the values above (this spreads load when many endpoints recover at once).

Delivery log

Every attempt — successful or not — is persisted. For each delivery you can see:

• Timestamp and attempt number.
• HTTP status code and response body (truncated to a safe length).
• Full request headers and signed payload, exactly as we sent it.
• The event type and referenced deposit/invoice id.

Manual replay

Any past delivery can be re-sent from the dashboard. The replay carries the same payload (so your idempotent handler does the right thing) but with a fresh timestamp and signature, so your verification code still passes.

Test deliveries

From the webhook settings page you can fire a synthetic webhook.test event without creating a deposit. Use it to confirm end-to-end wiring before going live.

Install

Methods

One typed method per endpoint — the client mirrors the REST surface you can reach with a Bearer key:

• createDeposit · createInvoice — mint a payment or invoice.
• getDepositStatus (poll /check by id or token) · completeTestDeposit (drive a sandbox deposit to completed).
• getInvoice · getPayment — fetch a single record.
• listInvoices · listPayments · listCustomers — paginated lists (limit/offset).
• getBalance · listCurrencies — balance + supported coins/networks.
• verifyWebhookSignature — standalone HMAC verifier (named export; no client needed).

Creating a deposit

Verifying webhook signatures

Related

• Quick start — end-to-end example.
• API reference — what each SDK method wraps.

The simplest integration (Free & Pro)

You don't need this SDK to accept crypto. The most reliable integration — and the one that works on every plan — is a redirect: create the payment server-side, then send the customer to the paymentLink you get back. The hosted page handles coin/network selection, the QR code, the countdown, and confirmations for you.

The iframe widget below is a Pro upgrade that renders that exact checkout inside your own page, so customers never leave your domain. Everything else — webhooks, idempotency, metadata, test mode — is identical between the two.

Drop-in widgetPRO

Create the payment server-side with POST /api/crypto/deposits, then mount the iframe with the returned paymentToken:

ReactPRO

Lifecycle eventsPRO

The SDK forwards postMessage events from the iframe to your callbacks. The paymentToken is included on every event so you can route by checkout if you embed multiple at once.

Returns { iframe, token, destroy() }. Call destroy() to detach the listener and remove the iframe (e.g. when closing a modal).

Headless (render your own UI)

If you'd rather skip the iframe and render the address + QR yourself, the same public API powers the hosted page. This works on both Free and Pro — the Pro gate is only on the iframe SDK above, not on the JSON endpoints. Mint the payment server-side, then drive the customer flow from your own components:

Restrict who can embed (optional)PRO

By default the embed page is loadable from any merchant origin. Open API & Webhooks → Embed allowlist in your dashboard and add one origin per line (https://yourdomain.com, one per line). Once non-empty, /embed/pay/<token> will only render when the request's Referer origin matches a line in your allowlist; any other site sees an inline "Embed not authorized" notice instead of the checkout. Empty list = no allowlist, which is the default.

Programmatically, the same value lives on PUT /api/branding as allowedEmbedOrigins: string[] — max 25 entries, each must parse to a canonical http(s) origin (scheme + host + non-default port; no paths).

How pricing works

When auto-convert is enabled for a currency, the hosted /pay page quotes the customer 1.01× the normal crypto amount. Once the deposit confirms, we place a limit-sell at market × 0.99 on the source exchange's <COIN>USDT pair. Best case the limit fills and you net ~100% in USDT — the 1%/1% buffer absorbs slippage. Limit unfilled after 5 minutes? We cancel and fall back to a market sell. Both legs are executed on-exchange, no third-party DEX or aggregator involved.

Toggle per currency

Step-up authentication required. Cookie session only (this is a management endpoint and rejects API-key auth with 403).

Successful response

Error: trading permission missing

Before enabling, we probe the exchange's spot-trading permission. If the API key isn't allowed to trade, the request fails with a structured error your UI can map to a click-path ("Account → API → Enable Spot Trading") per exchange:

Lifecycle field

Every Deposit row carries an autoConvert sub-object with status:

• null — auto-convert wasn't enabled, or the deposit hasn't terminated yet.
• pending — limit-sell placed; waiting for fill.
• filled — terminal. USDT received; receivedUsdt populated.
• failed — terminal. Both limit and market fallback failed; we email the merchant (throttled to 1 per exchange per 24h).
• skipped — terminal. Order not placed (below exchange minimum notional, no trading client, etc.).

deposit.auto_converted webhook

Subscribe to this event if you only care about the USDT-equivalent amount. deposit.completed fires earlier (when funds confirm on-chain) and won't have the conversion outcome.

Manual retry

Owner-only. Re-runs the pipeline for a deposit whose previous attempt was failed or skipped. Returns 409 if a retry is already in-flight (status =pending).

Supported exchanges

36 exchanges currently support trading-API auto-convert: Binance, MEXC, Bybit, Kraken, KuCoin, OKX, Bitget, Coinbase, Gate.io, BingX, LBank, Crypto.com, HTX, Bitfinex, Gemini, CoinEx, XT, Toobit, CoinW, WEEX, Bithumb, Bitstamp, Bitpanda, Tokocrypto, Bitvavo, WhiteBIT, VALR, Bitso, CoinDCX, BTCTurk, Upbit, WazirX, Coins.ph, Independent Reserve, Quidax, BitMart. Per-exchange permission help (name + click-path) is surfaced in the help field of the TRADING_PERMISSION_REQUIRED error above.

Bearer tokens

Mobile clients authenticate with an opaque ecp_m_… bearer token issued at sign-in. The token is SHA-256-hashed server-side; the raw value only lives in the device's secure storage (Keychain / Keystore). TTL is 90 days and slides on each authenticated request.

Mobile bearers unlock the same endpoint surface as a browser session — the full merchant dashboard — not the narrower API-key scope. Send the token as Authorization: Bearer ecp_m_….

Sign-up

Mirrors the web sign-up but returns the bearer in the JSON body (no cookie) and accepts device + push metadata in the same call. The default Business is created in the same transaction.

Returns { token, expiresAt, ttlSeconds, user, business }. Errors: 400 invalid email/password, 409 duplicate email.

Sign-in

Same body shape as sign-up minus name. When the account has 2FA enabled, the response is { requires2fa: true, method: "TOTP" | "EMAIL", challengeToken, expiresInSeconds, email } and the client posts the code to /api/auth/mobile/2fa/verify (with the challenge token) to receive the bearer.

For email-OTP 2FA, the same endpoint sends the code to the account email; resend is POST /api/auth/mobile/2fa/email/resend (throttled 3/5min/IP, 4/30min/user).

Session management

• POST /api/auth/mobile/sign-out — revoke the current bearer (idempotent).
• GET /api/auth/mobile/sessions — list this user's active mobile sessions; current row is flagged isCurrent.
• DELETE /api/auth/mobile/sessions — revoke every session except the current one ("sign out everywhere else").
• DELETE /api/auth/mobile/sessions/[id] — revoke a specific session.
• POST /api/auth/mobile/switch-business — change the active business for this device. Bearer does not rotate (cookie sessions re-mint the JWT on switch; mobile bearers are opaque, so the row is the source of truth).
• PUT /api/auth/mobile/device — update device metadata or push token. Pass pushToken: null to unregister from push.

Step-up (sudo) on mobile

The same gates that prompt for password re-verification on the web (live API-key creation, exchange config edits, etc.) apply on mobile. Difference: the sudo token comes back in the JSON body and the client sends it on the next sensitive call as X-Sudo-Token: <raw>.

• GET /api/auth/mobile/step-up — current grace-window status.
• POST /api/auth/mobile/step-up — verify password (+ 2FA code) → returns sudoToken, valid for 10 minutes.
• DELETE /api/auth/mobile/step-up — end the grace window.

Push notifications

Lifecycle events fire Firebase Cloud Messaging v1 pushes to all of a business's registered devices. Currently: deposit.completed and invoice.paid (the friendlier framing wins when the deposit settles an invoice). Register the FCM token at sign-in / sign-up, or update it later via PUT /api/auth/mobile/device.

Issuing API keys

Sign in, head to Settings → API & Webhooks, and click Create key. Two flavours:

• ecp_live_… — production keys. Creating one requires a recent high-tier step-up (the challenge must be under 2 minutes old) so a leaked sudo cookie can't silently mint access; revoking one uses a normal step-up (5-minute window).
• ecp_test_… — sandbox keys. Same shape; deposits and invoices are flagged isTest: true and excluded from balance, charts, customer rollups, and stats.

Where Bearer keys work

Programmatic access is scoped to the read/write payment surface:

• GET /api/crypto/currencies
• POST /api/crypto/deposits · GET /api/crypto/deposits/:id/check · POST /api/crypto/deposits/:id/test-complete
• GET /api/invoices · POST /api/invoices · GET /api/invoices/:id
• GET /api/payments · GET /api/payments/:id
• GET /api/customers
• GET /api/balance

Management routes (branding, team, billing, exchange config, plans, site config) reject Bearer auth with 403. Use the dashboard.

CSRF

State-changing cookie-authenticated requests must send an Origin header matching https://easycryptopay.xyz. Bearer-authenticated requests skip the check (browsers don't send Authorization cross-origin without explicit CORS, so CSRF isn't reachable). Public endpoints under /api/pay and the OAuth callback are exempt.

Error response shape

Every error returns JSON in the form { "error": "<message>" }. Routes that want fine-grained client handling add a code field.

HTTP status codes

Named error codes

Branch on code (not message strings).

STEPUP_REQUIRED

Sensitive mutations (delete a business, regenerate a webhook secret, change exchange credentials, create a live API key, change email) need a recent password re-check. POST to /api/auth/step-up with {password, code?} (code is required when 2FA is on), then retry the original request.

IDEMPOTENCY_CONFLICT

Same Idempotency-Key replayed within 24 hours but the body differs. Pick a fresh key.

IDEMPOTENCY_IN_PROGRESS

The same Idempotency-Key is still being processed by an earlier request (the slot is reserved before any side effect runs). Wait a moment and retry the identical request — you'll get the original response once it settles.

TRADING_PERMISSION_REQUIRED

Returned by PUT /api/crypto/auto-convert when the connected exchange's API key lacks spot-trading permission. Response carries help (per-exchange click-path) and exchangeName. See the Auto-convert section for an example.

Other codes you may branch on

The full registry lives in constants/error-codes.ts (and the OpenAPI spec). The most common caller-actionable ones:

Some older routes still emit { "error": "…" } with no code — that shape stays valid for back-compat, so fall back to the HTTP status when code is absent.

Rate limits

Rate limits are enforced at the openresty (nginx) layer with these burst thresholds:

Limits are per-IP. When breached, nginx returns a bodyless 429. Production traffic should never get close — design your retry to back off on 429 and 5xx.

Response shape: { <items>, total, limit, offset, stats } where <items> is the resource-named array (e.g. payments, invoices), total is the count of rows matching your filters, and stats is endpoint-specific aggregate data. On /api/customers the unfiltered business-wide count lives in stats.total. (Withdrawals cap limit at 100; the others at 200.)

Field naming (snake_case & camelCase)

Newer endpoints (/api/crypto/deposits, /api/balance) return camelCase. The older merchant-facing endpoints (/api/invoices, /api/payments, /api/customers) historically returned snake_case and now dual-emit both shapes so existing integrations keep working. Every row carries the snake_case key (payment_token, created_at, amount_usd…) AND its camelCase alias (paymentToken, createdAt, amountUsd…) with the same value.

My checkout says "No payment methods available"

For live payments the currency picker is built from your wallet addresses, so with no exchange connected there are none to show. Connect an exchange under Dashboard → Setup and make sure at least one deposit address exists for the coins you want to accept (required on both Free and Pro). Your POST /api/crypto/deposits calls still succeed and return a link; the live link just has nothing to offer until a wallet exists. Test mode is different — ecp_test_ payments serve a synthetic catalog and mint TEST_ addresses, so the picker works with no exchange at all.

My embed shows "Embedded checkout is a Pro feature"

The in-page iframe widget (embed.js) is Pro-only. On a Free plan the iframe renders an upgrade notice and fires onError with code: "pro_required". Either upgrade to Pro, or switch to the hosted-link redirect — that works on every plan and is the recommended path for most integrations. Your REST API calls are not gated; only the in-page iframe is.

My webhook isn't firing

• Check the URL in Settings → Branding isn't pointing at a private/loopback IP — we refuse those at save time (SSRF guard).
• Open Settings → Branding → Recent deliveries — every attempt is recorded, with status, error, and the next retry time. Failed deliveries can be replayed manually from there.
• Click Test delivery — fires a synthetic webhook.test event without creating a deposit. Confirms wiring end-to-end.

Signature verification keeps failing

My test deposit doesn't show in the dashboard

Sandbox rows (created with ecp_test_* keys) are filtered out of every aggregate the merchant dashboard shows: balance, payments list, invoices list, customer last-5, charts, and stats. That's by design — sandbox traffic must never touch live accounting. Test deposits still fire webhooks (with isTest: true in the payload) so you can integrate against them.

Auto-convert returns TRADING_PERMISSION_REQUIRED

Your exchange API key has deposit-read permission but not spot-trading. The error response carries a help object with the exact menu path on your exchange. Enable trading, save, then retry the toggle.

Idempotency-Key conflicts

A 409 IDEMPOTENCY_CONFLICT means you reused a key within 24h with a different body. Either: replay with the original body (you'll get the cached response), or pick a new key (typically your own order id, an order-revision counter, or a UUID per attempt).

Versioning & deprecations

• Webhooks carry an apiVersion field (currently "1"). Additive changes (new fields inside data) do not bump it — ignore unknown keys. Breaking changes bump the major and ship alongside v1 for a deprecation window.
• OpenAPI is versioned in its info.version at /openapi.json; the Node SDK follows semver.
• Field naming. The legacy list endpoints emit both snake_case and camelCase keys. camelCase is canonical; the snake_case aliases are deprecated and will be removed in a future major version — branch on the camelCase fields.
• Deploys & status. /api/version reports the running build + commit; /api/health reports a live DB probe.