Create
Your backend creates a USD invoice using a merchant key.
GATEWAY DOCUMENTATION REST API · v1.1
Payments, connected.
Bring crypto checkout to your website or app.
Create an invoice,
send your customer to checkout, and fulfill after verified payment.
BASE URL
Collect
Hosted checkout sends crypto directly to your linked wallet.
Confirm
Verify the invoice or signed webhook before fulfilling an order.
GET STARTED
From order to checkout.
Link a receiving wallet, enable supported assets, and create an API key in Integration. Compute the order price on your backend, then create an invoice with a stable order-specific retry key.
Example response
201 Created
Keep the invoice tied to your order.
Save the returned invoice ID before redirecting. Resolve
checkoutPath against your gateway origin; do not append
it to /api. A repeated Idempotency-Key returns the
first invoice, even if the request body changes.
ACCESS & TRUST
Your server holds the key.
Send Authorization: Bearer YOUR_MERCHANT_KEY from your
backend. Create and revoke keys while signed in to Integration. Keys
are shown once; store them as backend secrets.
Website / mobile app→Your backend→Coinvay API
Hosting access is a separate layer.
Coinvay checkout and developer documentation are publicly accessible. Merchant records require an authorized account or a scoped merchant API key. Administration requires an administrator account. Do not copy browser cookies into integrations. Cross-origin browser requests are not the integration pattern.
Never ship your merchant key or webhook secret inside a JavaScript bundle, Android app or iOS app. Your frontend calls your own authenticated backend to start checkout. Billing and administration are interactive account operations; merchant keys cannot grant plans or create more keys.
Automatic subscription setup and cancellation guide ↗
API access, webhooks, branding and recurring invoices depend on your
current plan. Administrator changes can alter features and limits.
PAYMENT LIFECYCLE
A verified payment, not a guess.
-
Create and save the invoice.
Use the price from your own order database, not a client-supplied total. Save its ID against the order.
-
Redirect to hosted checkout.
The customer chooses an enabled network and asset. Checkout locks an exact crypto amount and wallet for up to 20 minutes (Bitcoin: 120 minutes).
-
Wait for confirmation.
The gateway checks the successful canonical transaction, recipient, asset, amount, timing and confirmations. A submitted hash or pending result is not payment.
-
Verify and fulfill once.
Use
GET /api/invoices/{id}from your backend, or a verified webhook. Match the saved order, amount and currency; commit fulfillment once in your own database.
New→Paidor Expired / Cancelled
A return to your website is not proof of payment. Existing unpaid invoices can receive confirmation later; keep checking the server state. Do not send new funds after quote expiry. An active checkout polls every 10 seconds; unattended monitoring needs the separately configured server runner.
Where the money goes
Customer invoice payments settle to the merchant’s verified wallet. Merchant plan fees settle to the administrator’s subscription receiving wallets, selected in Admin → Plans & billing. The gateway does not hold merchant balances.
EVENTS
Connect payment to fulfillment.
Configure a public HTTPS postback in
Settings. Rotate the signing
secret once and save it on your backend. The signed event is
payment.completed.
| Header | Meaning |
|---|---|
X-Gateway-Signature |
HMAC-SHA256 hex of timestamp + . + exact raw body
bytes.
|
X-Gateway-Timestamp |
Unix seconds. Check freshness; the example allows five minutes. |
X-Gateway-Event-Id |
Delivery identifier, hook_…. Distinct from the
signed payment ID.
|
Loading verifier…
Verify first. Deduplicate durably.
Use the exact raw request body before JSON middleware changes it.
The delivery-ID header is not part of the signature; deduplicate
using the signed payload id and invoice/order identity.
Match your saved order and USD amount. Commit a unique payment
record and fulfillment/outbox job atomically, then return 2xx.
View payment.completed payload
The verifier checks authenticity and freshness; your application must implement its own durable order transaction. Do not deduplicate only in process memory. Return 2xx within eight seconds after durable acceptance; use a worker for slow fulfillment. Delivery redirects are rejected.
Events are queued. An authenticated runner handles unattended retries: up to three eligible deliveries per tick, at least one minute between automatic attempts, up to six automatic attempts. Manual Retry is available in Integration. Disabled webhook access pauses delivery. Secret rotation affects queued retries.
REST ENDPOINTS
Merchant API reference.
JSON request and response bodies. Paths are relative to this gateway origin. This covers merchant integrations; internal account-security, billing and administrator APIs are outside this reference.
Loading API reference…
BLOCKCHAIN SUPPORT
Choose the right network.
| Network | Chain ID | Assets | Confirmation policy |
|---|
The token registry is fixed on the server. Checkout returns only the merchant’s enabled options with linked wallets. Solana supports native SOL, not SPL tokens. Bitcoin, Tron TRX/USDT TRC-20 and native TON are supported; TON jettons are not. Testnet assets cannot pay for real merchant plans. Treat smallest-unit quantities as integer strings.
RELIABILITY
Handle the edges.
Checkout also has an aggregate 600 requests per IP per minute. Plan
invoice and API-key allowances apply separately. Errors return
{"error":"Human-readable message"}.
| Status | What to do |
|---|
Use bounded exponential backoff for 429 and temporary provider errors. A 429 currently has no Retry-After header. Retry ambiguous invoice creation with the same Idempotency-Key. Treat 400, 402 and 409 as conditions to resolve rather than blindly retry.