Checking payment network…
FLOW API / VERSION 1

Build payments into
your flow.

Create hosted Lightning checkouts, share product links, track transactions, and receive signed payment events.

01 / THE BASICS

Getting started

Create an account, then generate an API key in Dashboard → Developers. Keep the key on your server. The API base URL is the address of your Flow API deployment. Local development defaults to http://localhost:4000.

Check your network

The banner identifies regtest, testnet, or mainnet. Regtest and testnet sats have no mainnet value. Current dashboard keys start with flw_test_.

Your first checkout

HTTP
POST /v1/checkouts
Authorization: Bearer YOUR_FLOW_API_KEY
Content-Type: application/json
Idempotency-Key: order-1042

{"amount":"2500","description":"Coffee","reference":"order-1042"}

The response includes an id, hosted url, invoice when available, status, and network. Send the customer to the hosted URL, then confirm payment through the API or a webhook.

02 / ACCESS

Authentication

Send your API key as a bearer token with every /v1 request. Never expose it in browser code or a public repository.

HTTP
Authorization: Bearer flw_test_...

Every mutating /v1 request requires an Idempotency-Key header of 8–200 characters. Reuse a key only to retry the same request. Reusing it for different input returns a conflict.

03 / ACCEPT PAYMENTS

Checkouts & payments

POST /v1/checkouts and POST /v1/payments create a checkout from the same body. Amounts are positive integer sats encoded as strings, up to 100,000,000.

FieldMeaning
amountRequired. Amount in sats as a string.
descriptionRequired. 1–280 characters.
referenceRequired. Your order reference, 1–80 characters.

Use GET /v1/checkouts/:id or GET /v1/payments/:id to retrieve a checkout. GET /v1/transactions returns the latest 50 payments.

Node SDK

TYPESCRIPT
import { Flow } from "@rpay/flow";

const flow = new Flow({
  apiKey: process.env.FLOW_API_KEY!,
  baseUrl: process.env.FLOW_API_URL,
});
const checkout = await flow.checkouts.create({
  amount: "2500",
  description: "Coffee",
  reference: "order-1042",
});
console.log(checkout.url);
STOREFRONTS

Storefronts & buyer details

Each business has a public storefront URL in Dashboard → Products. It lists active products. A buyer chooses a product, provides an email and optional name, then continues to a Lightning invoice. Public reads use GET /public/stores/:businessId; checkout creation uses POST /public/stores/:businessId/products/:productId/checkout.

HTTP
POST /public/stores/BUSINESS_ID/products/PRODUCT_ID/checkout
Content-Type: application/json

{"buyerName":"Ada","buyerEmail":"ada@example.com"}

Buyer contact details are self-reported and are not verified by Lightning. They appear in authenticated merchant payment responses and payment.paid webhooks as buyerName and buyerEmail. Public checkout responses omit them.

05 / MOVE FUNDS

Withdrawals

Use POST /v1/withdrawals/bitcoin with an amount and exactly one of invoice or address. For local payouts, request a quote, review it, then create the withdrawal with a beneficiary.

HTTP
POST /v1/withdrawals/local/quote
{"amount":"10000","country":"NG","currency":"NGN"}

POST /v1/withdrawals/local
{
  "quoteId":"QUOTE_ID",
  "amount":"10000",
  "country":"NG",
  "currency":"NGN",
  "beneficiary":{
    "destinationType":"bank",
    "accountName":"Ada Example",
    "accountNumber":"0123456789",
    "bankCode":"BANK_CODE"
  }
}

Local payout availability depends on the deployment and supported corridors. Retrieve a withdrawal with GET /v1/withdrawals/:id.

06 / STAY IN SYNC

Webhooks

Add an HTTPS endpoint in Developer settings. Flow sends a payment.paid JSON event when a payment settles. The signing secret is shown once when you create the endpoint.

JSON
{"type":"payment.paid","data":{"id":"...","status":"paid","amount":"2500"}}

Verify x-flow-signature as a hex HMAC-SHA512 of the raw request body before processing. The SDK exposes flow.webhooks.verify(rawBody, signature, secret). Make your handler idempotent. Delivery is currently best effort without automatic retries, so reconcile important orders with GET /v1/payments/:id.

JSON
const valid = flow.webhooks.verify(
  rawBody,
  request.headers["x-flow-signature"] ?? "",
  process.env.FLOW_WEBHOOK_SECRET!
);
if (!valid) throw new Error("Invalid signature");
07 / TROUBLESHOOTING

Errors & limits

Non-2xx responses include an error object with a message. Validate amounts, references, URLs, and idempotency keys before sending requests. Webhook endpoints require HTTPS, except localhost addresses used for development.

Fast path

Generate an API key, create a checkout with a unique reference, open its URL, and confirm paid before fulfilling the order.