Authentication
Public API (API key)
Call /v1/* routes with Authorization: Bearer fl_live_…. These routes use Base mainnet. The fl_test_ namespace is reserved and disabled.
Merchant session API (Portal JWT)
Key and webhook management routes under /merchant/developers/* use the existing merchant access session from the Portal. Do not call these routes with an API key.
Idempotency
When creating an invoice, send a unique Idempotency-Key for each intended invoice. Retry with the same key and the same normalized request for 24 hours. A different request with the same key returns 409 IDEMPOTENCY_KEY_REUSED. A committed replay returns the original status, body, and location, with a new X-FinLinks-Request-Id.
Amounts are decimal strings. Invoice, balance, and ledger reads are scoped to the authenticated merchant and Base. A payment link points to the hosted checkout when the invoice is payable.
Webhook receivers
Register a dedicated public HTTPS endpoint. The backend returns its signing secret once. To verify a delivery:
- Read the raw request body before parsing JSON.
- Read the Unix-second value in
X-FinLinks-Webhook-Timestampand reject timestamps more than five minutes in either direction. - HMAC-SHA256 the UTF-8 timestamp, one period, and the raw body with the endpoint secret. Decode the hex signature in
X-FinLinks-Webhook-Signatureand compare equal-length digests in constant time. - Deduplicate side effects using
X-FinLinks-Event-Idand acknowledge with a2xx.X-FinLinks-Delivery-Ididentifies this delivery attempt.
Automatic business events are restricted to invoices created through the developer API. Observed outcomes include invoice.paid for fully paid and overpaid invoices, invoice.underpaid, invoice.expired, and invoice.cancelled. A payment already bound before expiry can produce invoice.paid after an earlier invoice.expired. An endpoint receives future observations while it is enabled. Delivery is at least once and ordering across events is unspecified.
Test calls perform one synchronous attempt. Manual replays queue one attempt. Both require an Idempotency-Key. Retries and replays keep the event ID and exact body. They use a fresh signing timestamp and delivery ID. The log shows the last seven days, with a scan limit of 4 KiB for responses. The sanitized preview can include a boolean received and one supported ACK status, with other values omitted. A timed-out or crashed attempt can have an unknown receiver outcome, so receivers should deduplicate.
Interface groups
Public API (API key)
POST /v1/invoicesGET /v1/invoicesGET /v1/invoices/{id}GET /v1/balancesGET /v1/ledger
Merchant session API (Portal JWT)
POST/GET /merchant/developers/keysPOST /merchant/developers/keys/{id}/rollPOST /merchant/developers/keys/{id}/revokePOST/GET /merchant/developers/webhooks/endpointsPOST /merchant/developers/webhooks/endpoints/{id}/disablePOST /merchant/developers/webhooks/testGET /merchant/developers/webhooks/deliveriesPOST /merchant/developers/webhooks/deliveries/{id}/replay