CoinsFlow Payments API

Send your key as a Bearer token on every request. Keys look like cf_live_<prefix>_<secret>.

Authorization: Bearer cf_live_3f9a0c1d2e4b5a6f_9sQ…

We store only a hash of the secret, so a lost key cannot be shown again: rotate it in the dashboard, and the old key stops working immediately. Suspended merchants' keys are refused with 401. Keys cannot withdraw unless you allow it, and can be locked to your server's IP addresses: see Keys, permissions and IP allowlists.

https://api.coinspath.net

Requests with a body must send Content-Type: application/json. Responses are JSON. Times are ISO 8601 in UTC.

Every amount, in requests and responses, is a decimal string in whole units of the asset: "0.015" BTC, "49.99" USDT. Never send or parse them as JSON numbers; floating point cannot represent them exactly.

Give either amount (exact crypto) or priceAmount (USD). With a USD price we lock the current rate when the invoice is created and round the crypto amount up by at most one base unit, so you are never short.

Use the chain id exactly as written. An invoice is paid at its confirmationsRequired, and settled (withdrawable) at the chain's final depth.

USDT and USDC exist on three networks. They are different tokens with different contracts: a customer paying a tron USDT invoice must send TRC-20 USDT. The hosted page warns them about this.

1. 1 · pending
   You create the invoice and send the customer to paymentUrl.
2. 2 · detected
   The customer sends. On Bitcoin and Litecoin we see it in the mempool within seconds; on the other chains in its first block.
3. 3 · paid
   It reaches confirmationsRequired and is credited to your pending balance. Fulfil here.
4. 4 · settled
   It reaches final depth and becomes withdrawable.

Typical time from sending to paid:

Small invoices on the two slow chains need fewer confirmations because reorganising even one block to steal them would cost far more than they are worth. Withdrawal always waits for the chain's full final depth, whatever the invoice.

What the customer pays in network fees (the fee is theirs, on top of the invoice amount):

For the lowest customer fees, offer Litecoin or BNB Smart Chain. Our addresses are native SegWit on Bitcoin and Litecoin, the cheapest kind to send to.

A payment that is still in the mempool keeps an invoice open past its deadline: it was sent in time. If it is dropped instead of mined (replaced by fee or double-spent), the invoice goes back to pending, or to expired if its time is up.

Block reorganisations are handled for you: if a confirmed payment is reorganised out of the chain, the invoice steps back to confirming and the credit is reversed. That is why you should treat paid as final only for goods you can take back, and wait for settled for anything irreversible and large.

GET /v1/invoices/{id} includes payments: each on-chain transfer to the invoice address, oldest first, with txid, amount, confirmations, status, blockHeight and seenAt.

Several payments to one invoice add up (a customer topping up after an underpayment). Anything sent to an invoice address in a different asset is still credited to you, as a deposit.

Attach up to 20 key/value pairs to an invoice with metadata. Keys are 1 to 40 characters; values are strings (up to 500 characters), numbers, booleans or null. They come back on every read of the invoice and are never shown to the customer (unlike orderId and description, which the payment page displays).

"metadata": { "customerId": "c_8812", "plan": "pro", "seats": 3 }

Send an Idempotency-Key header (1 to 200 characters, e.g. your order id) when creating an invoice. Retrying with the same key and the same body returns the original invoice instead of creating a second one, even when retries run at the same moment: one of them creates it, the others get 409 idempotency_in_progress until it exists, then the same invoice. The same key with a different body is refused with 409 idempotency_key_reuse. Keys are kept for 30 days.

1. Create the invoice from your server, with an Idempotency-Key (your order id works) so a retry never makes a second invoice.
2. Store the invoice id against your order. Put your own references in orderId or metadata.
3. Never fulfil because the customer came back from the payment page. Fetch GET /v1/invoices/{id} from your server and check status.
4. Fulfil at paid, overpaid or settled. For something large and irreversible, wait for settled.
5. Treat detected as “payment on its way”, not as paid. It can still be replaced or double-spent until it is in a block.
6. Handle underpaid (ask for the rest, same address) and paidLate (the money arrived after the deadline; you decide whether to honour the price).
7. Use webhooks to hear about payments at once, verify the signature, and still confirm with GET /v1/invoices/{id} before shipping anything valuable.

Errors return a JSON body with a stable machine-readable error code and a human detail.

{
  "error": "unsupported_asset",
  "detail": "USDT is not available on bitcoin. Supported: BTC."
}

A new key can create and read invoices and read balances. It cannot move money. To withdraw over the API, open Developers in the dashboard, turn on Allow withdrawals with this key and list the IP addresses your server calls from. This needs two-factor authentication on your account, and your password.

With an allowlist set, the key is refused from any other address on every endpoint with 403 ip_not_allowed. Single addresses and CIDR blocks work, IPv4 and IPv6. Rotating the key keeps its permissions and allowlist.

Send your settled (withdrawable) balance to any address on the same network. The amount you ask for is what arrives; a fee, quoted up front in the same asset, is taken from your balance on top.

The fee covers every network cost of the withdrawal. Usually that is one transaction. When the funds first have to be brought together on the network (for example a token balance spread over several deposit addresses), those extra transactions are priced in too, and the quote says how many (networkTransactions). Quote with the amount and destination you will use to get the exact fee, and pass it as maxFee when you create the withdrawal: you are never charged more than that. If network fees jump after the quote so that the fee no longer covers sending, the withdrawal is not sent and the amount and fee go back to your balance; quote again. If a withdrawal fails after network fees were already spent on it (for example, a transaction that failed on chain), the amount comes back and the fee pays for those network fees.

1. 1 · requested
   You ask. Amount + fee are reserved from your withdrawable balance.
2. 2 · approved
   Automatically, up to your daily limit (USD 5,000 by default). Larger amounts are reviewed by our team first.
3. 3 · broadcast
   Signed and sent, usually within a minute of approval. txid is set.
4. 4 · confirmed
   Confirmed on chain. You get a webhook and an email.

Minimums (below these the fee would eat most of the amount):

Destination addresses are checked strictly, checksum included: a mistyped Bitcoin or TRON address, a Litecoin address on Bitcoin, or a mixed-case Ethereum address with a wrong EIP-55 checksum is refused with 400 invalid_destination before anything happens. You cannot withdraw to a CoinsFlow deposit address.

Add an endpoint in the dashboard (Developers) or with POST /v1/webhooks, and we POST a signed JSON event to it every time an invoice or withdrawal changes status. The event is queued in the same database transaction as the change, so none is ever lost.

POST /webhooks/coinsflow HTTP/1.1
Content-Type: application/json
User-Agent: CoinsFlow-Webhooks/1.0
CoinsFlow-Event: invoice.paid
CoinsFlow-Delivery: 5d0b8a52-6c1e-4f7a-9b3d-2e8f0a1c4b6d
CoinsFlow-Signature: t=1790590000,v1=5f3c9a0e...c21d

{
  "id": "5d0b8a52-6c1e-4f7a-9b3d-2e8f0a1c4b6d",
  "type": "invoice.paid",
  "createdAt": "2026-09-26T10:05:40.000Z",
  "previousStatus": "confirming",
  "data": {
    "object": "invoice",
    "id": "4f1c9e2a-7b3d-4c1e-9a55-2d8e6f0b1c34",
    "status": "paid",
    "chain": "tron",
    "asset": "USDT",
    "address": "TDCzDbXt9qSJrH9ZDyg4TBMjdTteKhQm5N",
    "amountDue": "49.99",
    "amountPaid": "49.99",
    "orderId": "order-1042",
    "metadata": { "customerId": "c_8812" },
    "priceAmount": "49.99",
    "priceCurrency": "USD",
    "usdValue": "49.99",
    "expiresAt": "2026-09-26T11:00:00.000Z",
    "createdAt": "2026-09-26T10:00:00.000Z",
    "settledAt": null,
    "payments": [
      { "txid": "8f3c1a…e9d2", "amount": "49.99", "confirmations": 20, "status": "confirming" }
    ]
  }
}

data is the invoice (or withdrawal) as it is when we send, with the same fields as the API. Events can arrive out of order and more than once: use the event id to ignore repeats, and trust data.status over the event name. A ping event (from Send test) has {"type":"ping"} as its data.

Every request carries CoinsFlow-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of <t>.<raw body> keyed with your endpoint's secret (whsec_…). Recompute it over the raw bytes, compare in constant time, and reject anything older than five minutes so a captured request cannot be replayed.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.COINSFLOW_WEBHOOK_SECRET; // whsec_...

// Verify over the RAW body: parsing and re-serialising JSON changes the bytes.
app.post("/webhooks/coinsflow", express.raw({ type: "application/json" }), async (req, res) => {
  const parts = Object.fromEntries(
    (req.get("CoinsFlow-Signature") ?? "").split(",").map((p) => p.split("=", 2)));
  const expected = crypto.createHmac("sha256", SECRET).update(`${parts.t}.${req.body}`).digest("hex");
  const fresh = Math.abs(Date.now() / 1000 - Number(parts.t)) < 300;
  const ok = fresh && typeof parts.v1 === "string" && parts.v1.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  if (!ok) return res.sendStatus(400);

  const event = JSON.parse(req.body);
  if (await alreadyHandled(event.id)) return res.sendStatus(200); // retries reuse the id
  if (event.type === "invoice.paid") await fulfilOrder(event.data.orderId, event.data);
  res.sendStatus(200); // answer quickly; do slow work in a queue
});

Answer with any 2xx within 10 seconds. Anything else (an error status, a redirect, a timeout, a refused connection) is retried:

You can see every delivery, its response and its next retry in the dashboard, and send any of them again. An endpoint that has failed without a single success for five days is paused (turn it back on in the dashboard). Endpoints must use https:// on the public internet; we do not follow redirects and never call private or internal addresses.

curl https://api.coinspath.net/v1/webhooks \
  -H "Authorization: Bearer $COINSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://shop.example.com/webhooks/coinsflow",
    "events": ["invoice.paid", "invoice.settled", "invoice.expired", "withdrawal.confirmed", "withdrawal.failed"],
    "description": "Order fulfilment"
  }'

Bitcoin Lightning: instant, very low-fee Bitcoin payments alongside the normal on-chain address.

Questions? Use the chat bubble at the bottom right of any page.