CoinsFlow Payments API

1. 1Create an account and add a merchant (one per store). Copy the API key it shows you; it is shown only once.
2. 2From your server, POST /v1/invoices with the chain, asset and price.
3. 3Redirect the customer to the paymentUrl in the response. It shows the address, amount, a QR code and live status.
4. 4Check the invoice with GET /v1/invoices/{id}. Fulfil the order once its status is paid, overpaid or settled.

curl https://api.coinsflow.app/v1/invoices \
  -H "Authorization: Bearer $COINSFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042" \
  -d '{
    "chain": "tron",
    "asset": "USDT",
    "priceAmount": "49.99",
    "orderId": "order-1042",
    "description": "Pro plan, 1 month"
  }'

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.coinsflow.app

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.

ETH, BNB or TRX sent from inside a smart contract (a contract wallet, an exchange’s batch payout) is credited like any other payment. Such a transfer has no transaction of its own addressed to you, so its txid reads internal:… instead of a transaction hash: treat txid as an opaque id, not always something to look up in an explorer.

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.

Pay what you want. For donations, tips and top-ups, create the invoice with openAmount: true and no amount or priceAmount. The payment page asks for any amount. The invoice goes to detected when a payment is seen, paid once it has its confirmations and settled at final depth, whatever the amount: it is never underpaid or overpaid. amountDue stays "0"; read amountPaid (and payments) to know how much arrived, and credit your customer for that. A later payment to the same invoice is credited to you and added to amountPaid, but the status does not change again, so no further webhook is sent for it. It must be asked for explicitly: a request with no amount and no openAmount is a 400, so a bug that drops your amount can never create an invoice anyone can settle with a cent. confirmationsRequired and usdValue are set from the amount once a payment is seen.

Pay with CoinsFlow. Customers who hold a CoinsFlow balance in the same asset on the same network can pay from it on the hosted page, confirmed with their password (and two-factor code, when on). There is nothing to confirm on-chain: the invoice goes through detected, paid and settled at once, with a webhook for each, and the amount (less your usual fee) is withdrawable immediately. Such an invoice has paidWith: "coinsflow" and an empty payments list. Handle it like any settled invoice; no change is needed in your integration.

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-29T10: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: for an invoice the same fields as the API, plus settledAt; for a withdrawal the core fields (id, status, chain, asset, destination, amount, fee, txid, networkFee, confirmations, orderRef, failureReason and the timestamps). Fetch the object from the API when you need everything. 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.coinsflow.app/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.