REFERENCE

API Reference

Complete list of all Flowwithlit API endpoints. Click any endpoint to expand its request / response details. Base URL: https://api.flowwithlit.com

ℹ️

Endpoints marked 🔑 Secret Key use your API secret key as a Bearer token. Everything else is either public or authenticated with your public key. Get your keys from the Developer API dashboard.

Payments

POST /v1/checkout/sessions Lock in amount/currency/email before opening checkout 🔑 Secret Key ▶

🔒

Call this from your own server (never the browser) before starting checkout — see Lock In the Amount Server-Side. Sessions expire after 30 minutes and can only be used once.

Authenticate with Authorization: Bearer flw_sec_test_YOUR_KEY

Field	Type	Required	Description
`amount`	number	required	Amount in kobo (lowest denomination)
`currency`	string	optional	Default: NGN
`email`	string	required	Customer email
`name`	string	optional	Customer name
`ref`	string	optional	Your transaction reference
`meta`	object	optional	Arbitrary metadata passed to webhooks

cURL

curl -X POST https://api.flowwithlit.com/v1/checkout/sessions \
  -H "Authorization: Bearer flw_sec_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"amount":500000,"currency":"NGN","email":"customer@example.com","name":"John Doe"}'

JSON response

{"status":true,"data":{"token":"cs_9f2a1c...","checkout_url":"https://checkout.flowwithlit.com/?session=cs_9f2a1c...&key=flw_pub_test_...","expires_at":"2026-07-26T14:32:00Z"}}

GET /public/rates Get exchange rates (no auth needed) 🌐 Public ▶

Returns current exchange rates relative to NGN. Used by checkout pages and merchant sites to display currency equivalents. No API key required.

JSON

{"status":true,"data":{"NGN_USD":0.00062,"NGN_GBP":0.00049,"NGN_EUR":0.00057,"USD_NGN":1610.0,"GBP_NGN":2040.0,"EUR_NGN":1750.0}}

GET /public/merchant-info Get merchant name for checkout display 🌐 Public Key (query param) ▶

Query Parameters

Field	Type	Required	Description
`key`	string	required	Your public API key

JSON

{"status":true,"data":{"merchant_name":"Acme Ltd","is_test":true}}

GET /public/checkout-session/{token} Read back the amount/currency/email locked into a session 🌐 Public (token is one-time) ▶

ℹ️

This is what the hosted checkout page calls when it's opened with ?session=... — you don't normally call it yourself. Returns 410 Gone once the session has been used or has expired.

JSON

{"status":true,"data":{"merchant_name":"Acme Ltd","public_key":"flw_pub_test_...","is_test":true,"amount":500000,"currency":"NGN","email":"customer@example.com","name":"John Doe","ref":"ORDER_1042"}}

POST /public/charge Process a card payment from the hosted checkout 🌐 Public Key (body) ▶

ℹ️

This endpoint is called by the hosted checkout page — you don't call it directly. Use FlowPay.init() on your frontend instead.

Field	Type	Required	Description
`public_key`	string	required	Your public API key
`session_token`	string	optional	Recommended. From `POST /v1/checkout/sessions`. When set, overrides `amount`/`currency`/`email`/`name`/`ref`/`meta` below with the session's stored values.
`amount`	number	required*	*Unless `session_token` is set. Amount in kobo (lowest denomination) — editable in the browser, see the session endpoint above
`currency`	string	optional	Default: NGN
`email`	string	required*	*Unless `session_token` is set. Customer email
`name`	string	optional	Customer name
`ref`	string	optional	Your transaction reference
`meta`	object	optional	Arbitrary metadata passed to webhooks

JSON

{"status":true,"data":{"status":"successful","transaction_ref":"FLW_TXN_ABCD1234","amount":500000,"currency":"NGN","message":"Payment successful"}}

GET /v1/transaction/verify/{ref} Verify a transaction by reference 🔑 Secret Key ▶

Authenticate with Authorization: Bearer flw_sec_test_YOUR_KEY

cURL

curl https://api.flowwithlit.com/v1/transaction/verify/FLW_TXN_ABCD1234 \
  -H "Authorization: Bearer flw_sec_test_YOUR_KEY"

JSON response

{"status":true,"data":{"status":"successful","transaction_ref":"FLW_TXN_ABCD1234","amount":500000,"currency":"NGN","customer":"john@example.com","created_at":"2026-06-15T10:32:44Z"}}

HTTP Status Codes

Code	Meaning	What to do
`200`	OK	Request succeeded
`400`	Bad Request	A required field is missing or invalid — check `message`
`401`	Unauthorized	Missing or invalid token / API key
`402`	Payment Required	Insufficient wallet balance
`403`	Forbidden	Valid token but not allowed (e.g. wrong role)
`404`	Not Found	Resource doesn't exist or doesn't belong to you
`429`	Too Many Requests	Rate limited — back off and retry
`500`	Server Error	Something went wrong on our end — contact support