Get started

CXPay API integration for custom checkout

The REST API at https://api.cxpay.cash/api/v1 powers hosted checkout, automation, and reporting. Use scoped API keys, Idempotency-Key on POST creates, and signed webhooks for reliable payment state.

Authentication and environments

API keys use cxpay_live_ and cxpay_test_ prefixes with scopes limiting access. Store secrets in environment variables—never commit them to git.

Point integrations at https://api.cxpay.cash/api/v1 for production unless your deployment docs specify otherwise.

Payment intents and checkout

POST /payment-intents with body { amountUsdCents, rail?, payerAsset?, metadata? }. Retrieve with GET /payment-intents/:id or list GET /payment-intents. Cancel with POST /payment-intents/:id/cancel.

Hosted checkout uses the client secret flow documented in developer docs on this site.

Links, invoices, refunds, exports

POST /payment-links, POST and GET /invoices(/:id), POST /refunds, GET /refunds/:id, GET /reports/payments, GET /exports/payments.csv, and webhook endpoint management round out merchant automation.

Cancel stale intents with POST /payment-intents/:id/cancel when shoppers abandon carts so dashboards stay tidy.

CXPay charges 1% on standard checkout, 0.5% when the payer selects the CXCASH rail (private, gas-free payments on Aztec via cxcash.app), and a $0.30 minimum fee per payment. There is no setup fee, monthly fee, or application fee in the product. Ethereum and Bitcoin network fees are shown to the payer at cost on those rails.

  • Idempotency-Key header on POST payment-intents
  • Webhook signature verification with cxpay-signature
  • CSV export for accounting

Webhook events

Events include payment.confirming, payment.paid, payment.succeeded, payment.underpaid, payment.overpaid, payment.expired, payment.failed, and payment.cancelled.

Delivery logs and secret rotation live in the merchant dashboard.

Read the quickstart

The /docs page includes curl examples, Node verification sample, status tables, and test versus live key guidance.

Configure webhook endpoints to receive signed POST requests when payment state changes. Parse the cxpay-signature header, reject stale timestamps outside the five-minute tolerance, and return quickly while processing asynchronously. Failed deliveries retry and may dead-letter; use dashboard delivery logs to diagnose URL typos, TLS issues, or application errors on your side.

The merchant dashboard and GET /reports/payments help you filter by status and time range. Download GET /exports/payments.csv when finance needs a spreadsheet-friendly view. Pair exports with webhook-driven order updates so internal systems stay aligned with on-chain settlement. Because CXPay does not hold balances, your wallet history and CXPay reports together form the reconciliation trail.

Production checklist

Server integrations should create payment intents with Idempotency-Key headers, persist the returned intent ID on your order row, and only mark paid after payment.succeeded verifies on your webhook handler. Test keys let you exercise the full lifecycle without touching live balances. WooCommerce merchants request the official plugin through the contact form and configure API base URL plus webhook secrets before going live.

Merchants who educate payers about exact amounts and quote expiry see fewer support tickets. Publish your accepted assets and networks on your store policy page and link to CXPay asset guides. When customers pay with ETH or BTC, remind them that network fees appear separately from the CXPay merchant fee. For audiences comfortable with Aztec, highlight CXCASH as a gas-free alternative through cxcash.app.

Merchant sign-up requires an email and password (or sign in with your existing CoinExchange account), a business name, and a payout wallet address. CXPay does not collect government ID, proof of address, business phone numbers, or KYB documents for onboarding. You are responsible for understanding obligations that may apply to your business in your jurisdiction.

Supported networks and assets today: Ethereum (ETH, USDC, USDT, DAI); Base (ETH, USDC, DAI — USDT is not supported on Base); Arbitrum (ETH, USDC, USDT); Optimism (ETH, USDC, USDT, DAI); Polygon (MATIC, USDC, USDT, DAI); Tron (TRX, USDT TRC20); Solana (SOL, USDC, USDT); Bitcoin on-chain (BTC) and Bitcoin Lightning (BOLT11); and CXCASH (gas-free private payments via cxcash.app).

Security practices for API keys

Store cxpay_live_ secrets in environment variables with least-privilege scopes. Never expose keys in browser bundles for payment intent creation.

Rotate compromised keys immediately and replay webhook tests after rotation.

Start accepting crypto payments

Create a merchant account with email, business name, and your payout wallet. No ID documents required.

Sign up free

Questions about this page

Is idempotency required?

Strongly recommended on POST /payment-intents to safely retry network failures.

What signature header do webhooks use?

cxpay-signature with t=<unix>,v1=<hex HMAC-SHA256 of "<t>.<raw body>"> and five-minute tolerance.

Can I embed checkout without hosted pages?

Use payment intents and the documented hosted checkout flow; see docs for integration patterns.

Are there SDK packages on this page?

This marketing site documents HTTP APIs; use curl or your HTTP client of choice.