Build payments into
your flow.
Create hosted Lightning checkouts, share product links, track transactions, and receive signed payment events.
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.
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
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.
Authentication
Send your API key as a bearer token with every /v1 request. Never expose it in browser code or a public repository.
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.
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.
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
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);Payment links
Create a product in the dashboard, then call POST /v1/payment-links with its productId and an idempotency key. Share the returned URL. The buyer opens the reusable link, enters contact details, then gets a fresh invoice for that purchase.
POST /v1/payment-links
Authorization: Bearer YOUR_FLOW_API_KEY
Idempotency-Key: product-link-1042
Content-Type: application/json
{"productId":"YOUR_PRODUCT_ID"}List links with GET /v1/payment-links or retrieve one with GET /v1/payment-links/:id.
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.
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.
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.
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.
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.
{"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.
const valid = flow.webhooks.verify(
rawBody,
request.headers["x-flow-signature"] ?? "",
process.env.FLOW_WEBHOOK_SECRET!
);
if (!valid) throw new Error("Invalid signature");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.
Generate an API key, create a checkout with a unique reference, open its URL, and confirm paid before fulfilling the order.