FlowNoc API

Base URL: https://flownoc.com/api/v1

FlowNoc is non-custodial payment infrastructure. Create invoices, send customers a hosted checkout, verify on-chain payments, and receive funds directly to wallets you control.

JSON request and response bodies. Creating invoices requires an active subscription, available transaction credits, and sufficient FlowNoc USD balance when a processing fee applies.

How FlowNoc works

1. Create an invoice from the dashboard or REST API.
2. The customer opens hosted checkout and pays a supported network/token.
3. FlowNoc detects the on-chain transfer, verifies destination, token and amount, then waits for required confirmations.
4. Crypto settles directly to the merchant-configured wallet. FlowNoc reports the result and, when configured, delivers a webhook.

Quickstart

1. Create a merchant in the dashboard and copy the API key.
2. Optionally call GET /merchant/checkout-networks to see enabled currencies and networks.
3. Call POST /merchant/checkout-session or POST /invoices with a fiat amount. Use the returned checkout_url (also pay_url).
4. Configure a webhook URL on the merchant, or pass notify_url per invoice.

Dashboard defaults: merchant Webhook URL is used when notify_url is omitted. Default success URL is used when success_url is omitted.

Authentication

API keys are issued per merchant. Send one of:

X-Api-Key: YOUR_KEY
Authorization: Bearer YOUR_KEY

The webhook signing secret (shown once when the merchant is created) verifies X-FlowNoc-Signature. Do not send private keys or seed phrases to FlowNoc.

Create an invoice

Omit chain and token for hosted fiat checkout. Optional lock: checkout_chain + checkout_token, or payment_network_id.

Fixed crypto: send chain, token, and amount as a decimal string in crypto units.

Do not combine fixed-crypto chain/token with hosted checkout lock fields.

List invoices

GET /api/v1/invoices?per_page=20

Paginated. Does not consume credits.

Retrieve an invoice

GET /api/v1/invoices/{id}

Returns current status and settlement fields including amount_received, amount_received_usd, surplus*, and shortfall*.

Invoice lifecycle

Typical path:

Pending → Detected → Confirming → Paid

Hosted checkout may sit on a network-selection state until the customer picks a network. After a network is locked, monitoring uses pending.

Payment outcomes

• Paid — within the paid band. Consumes one credit. Fires invoice.paid.
• Underpaid — below the paid band, within attribution. Consumes one credit. Fires invoice.underpaid.
• Overpaid — above the paid band, within attribution. Consumes one credit. Fires invoice.overpaid.
• Expired — window ended without a qualifying payment. Does not consume a credit.

Dashboard: underpaid/overpaid invoices can be marked paid, which fires invoice.paid.

Checkout flow

By default the customer opens checkout_url and picks currency and network. To skip the picker, pass chain+token or payment_network_id on checkout-session, or hosted lock fields on invoices.

POST /api/v1/merchant/checkout-session

Send a fiat amount, receive pay_url / checkout_url.

curl -X POST "https://flownoc.com/api/v1/merchant/checkout-session" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_KEY" \
  -d '{"amount":10.5,"note":"order_123"}'

Optional: currency (default USD), notify_url, success_url, return_url (aliases return_success_url / return_cancel_url).

Lock network and skip the picker:

-d '{"amount":10.5,"note":"order_123","chain":"bnb","token":"USDT"}'

When locked, response status is pending, with chain, token, pay_amount, and pay_to_address.

GET /api/v1/merchant/checkout-networks

Lists enabled admin networks ∩ this merchant's active wallets. Does not consume credits.

curl "https://flownoc.com/api/v1/merchant/checkout-networks" \
  -H "X-Api-Key: YOUR_KEY"

{
  "currencies": ["BNB", "USDT"],
  "networks": [
    {
      "payment_network_id": 12,
      "chain": "bnb",
      "token": "USDT",
      "label": "BNB Smart Chain · USDT",
      "network_label": "BSC (BEP-20)"
    }
  ],
  "networks_by_currency": {
    "USDT": [
      {"payment_network_id": 12, "chain": "bnb", "network_label": "BSC (BEP-20)", "label": "BNB Smart Chain · USDT"}
    ]
  }
}

Payment verification

FlowNoc attributes a transfer only when destination, network, token and amount match the invoice. Transfers outside attribution windows are ignored.

Confirmations

After detection the invoice moves to confirming until confirmations reaches required_confirmations for that network.

Underpayments

Paid band is about −0.2% to +2% of expected. Below that, down to about −2%, the invoice is underpaid. Processing fee uses verified received USD, not the expected amount. One credit is consumed.

Overpayments

Above the paid band up to about +10% is overpaid. Excess crypto still settles to the merchant wallet. Fee uses received USD. One credit is consumed.

Expired invoices

If the invoice window ends without a qualifying payment, status becomes expired and no credit is consumed.

Supported networks

Network configuration

Acceptance is the intersection of operator-enabled payment networks and the merchant's active wallets. Use checkout-networks before locking chain and token.

Webhooks

FlowNoc POSTs to invoice notify_url if set, otherwise the merchant webhook URL, when an invoice reaches a settlement status.

PATCH /api/v1/merchant/webhook

{"webhook_url":"https://yoursite.com/hook","callback_url":"https://yoursite.com/thanks"}

callback_url is the same field as Default success URL in the dashboard.

Events

• invoice.paid
• invoice.overpaid
• invoice.underpaid

Headers: X-FlowNoc-Signature, X-FlowNoc-Event, X-FlowNoc-Timestamp.

{
  "event": "invoice.overpaid",
  "event_id": "01H….invoice.overpaid",
  "invoice_id": "01H…",
  "merchant_id": 1,
  "status": "overpaid",
  "amount": "10.000000000000",
  "amount_expected": "10.000000000000",
  "amount_received": "10.500000000000",
  "amount_received_usd": "10.50000000",
  "amount_fiat": "10.00000000",
  "amount_fiat_received": "10.50000000",
  "fiat_currency": "USD",
  "surplus": "0.5",
  "surplus_usd": "0.50000000",
  "shortfall": null,
  "shortfall_usd": null,
  "token_symbol": "USDT",
  "chain": "bnb",
  "note": "order_ref",
  "tx_hash": "0x…",
  "paid_at": "2026-08-06T13:00:00+00:00",
  "nonce": "uuid",
  "sent_at": "2026-08-06T13:00:01+00:00"
}

Signature verification

Verify HMAC-SHA256 of the raw request body with the webhook signing secret. Compare to X-FlowNoc-Signature with a constant-time compare. Do not re-encode JSON before verifying. Event and timestamp headers are informational and are not included in the HMAC.

$sig = hash_hmac('sha256', $rawBody, $signingSecret);
hash_equals($sig, $request->header('X-FlowNoc-Signature'));

Delivery and retries

Failed deliveries are retried. Delivery is retry-aware, not guaranteed. Webhook URLs must be public HTTPS. Localhost, private networks, and cloud metadata addresses are rejected.

Handling duplicate events

Treat event_id (invoice public id + event) as the idempotency key. Retries may carry a new nonce / sent_at and therefore a different signature. Do not fulfill again because a delivery was retried.

POST /api/v1/invoices

Create a hosted fiat invoice or a fixed-crypto invoice. Same optional URLs as checkout-session.

{
  "amount": "100.00",
  "currency": "USD",
  "note": "Order #4821"
}

Response 201 includes id, status, checkout_url, and pay_url.

GET /api/v1/invoices

List invoices for the authenticated merchant. Query: per_page (1–100, default 20).

GET /api/v1/invoices/{id}

Fetch one invoice by public id.

HTTP status codes

• 401 — missing or invalid API key
• 403 — subscription_required, insufficient_credits, billing_balance_required, or account billing blocks
• 422 — validation error; see message

Troubleshooting

• New invoices blocked: confirm an active subscription, remaining credits, and FlowNoc USD balance.
• Webhook not arriving: confirm a public HTTPS URL, signature verification on the raw body, and that the invoice reached paid / underpaid / overpaid.
• Network lock rejected: the chain/token must match an enabled network and an active wallet.