Pay API integration guide
Integrate the LFG Pay API end to end — authentication, payment links, redirects, and signed webhooks. Everything in one page.
This is a complete, self-contained guide to the LFG Pay API. It's written so you can read it top to bottom — or paste the whole page into an AI assistant (Claude, ChatGPT) and ask it to build the integration for your framework.
Using an AI assistant? Copy this entire page and prompt it with something like: "Here are the LFG Pay API docs. Build a 'Pay with LFG' checkout in <your stack — e.g. Next.js / Laravel / Django>: create a payment link on my server, redirect the buyer to the checkout URL, and verify the settlement webhook."
How it works
The flow is three steps:
Create a payment link — your server calls the API with the amount and an order reference. You get back a
checkoutUrl.Redirect the buyer to that
checkoutUrl. LFG hosts the checkout, handles the on-chain payment and compliance screening, and returns the buyer to yoursuccessUrlwhen they're done.Receive a webhook — LFG POSTs a signed event to your server as the payment progresses, so you can fulfil the order automatically.
Base URL:
https://api.getlfg.app/pay/v1Content type:
application/jsonField casing: all request and response fields are
camelCase.
Everything is scoped to the business your API key belongs to — you never send a business ID, and a leaked key can only ever touch its own business.
Authentication
Create an API key in your dashboard under Settings → API Keys. You'll get two secrets, shown only once:
the API key (
lfg_sk_live_…) — used to authenticate requests.the webhook signing secret — used to verify webhooks (see below).
Store both in your server's secret manager. They're stored hashed on our side and cannot be retrieved again — if you lose one, revoke the key and create a new one.
Send the API key as a bearer token on every request:
The API key is a server-side secret. Never put it in browser code, mobile apps, or any public repository. All API calls must come from your backend.
Authentication errors
HTTP
code
Meaning
401
missing_api_key
No Authorization: Bearer … header was sent.
401
invalid_api_key
The key doesn't match any active key.
401
api_key_revoked
You revoked this key. Create a new one.
403
api_key_disabled
LFG disabled the key (see reason). Contact support.
403
business_disabled
The business account is disabled. Contact support.
401 means your credential is wrong — rotate it. 403 means LFG turned something off — a new key won't help; contact support.
Rate limits
60 requests per 60 seconds, per API key. The limit is per key, so your traffic is never affected by other merchants. Exceeding it returns 429.
Response format
Successful responses are wrapped in an envelope:
List endpoints add pagination fields (page, limit, total, totalPages) under meta.
Create a payment link
Request body
orderId
string
yes
Your own order reference. Echoed back on webhooks.
fiatAmount
number
yes
The amount to charge (positive).
token
string
yes
USDC or USDT.
network
string
yes
base or ethereum.
fiatCurrency
string
no
Defaults to your business currency (e.g. USD).
expiryMinutes
number
no
How long the checkout stays payable.
successUrl
string
no
Where the buyer returns after paying.
cancelUrl
string
no
Where the buyer returns on cancel/failure.
webhookUrl
string
no
Overrides the key's default webhook URL for this link.
skuMetadata
object
no
{ "items": [ … ] } line-item detail.
Example
Response 201
Redirect the buyer to checkoutUrl. LFG hosts the checkout, the on-chain payment, and compliance screening.
Always recompute the amount on your server from your own cart or order — never trust an amount sent from the browser.
List and fetch payment links
Returns your links, newest first, each with its current session, paginated.
Returns a single link (plus session), or 404 if it isn't yours.
Returning the buyer to your store
When the payment completes, the buyer sees an Order Confirmed screen on the LFG checkout. Closing it returns them to your successUrl, with these query parameters appended so you can reconcile the order:
order_id
Your original orderId.
link_token
The payment link token.
tx_hash
The on-chain transaction hash.
status
success.
On cancellation or a failed payment (wrong network/asset, underpaid, expired, screening failed), the buyer is returned to your cancelUrl with status=cancelled / failed / expired.
Treat the webhook — not the redirect — as the source of truth for whether a payment succeeded. A buyer can close the tab before returning; the webhook still fires.
Webhooks
If a payment link has a webhookUrl (either set per-request, or configured as the key's default), LFG sends a POST to it every time the payment session changes state — so you can fulfil orders without polling.
Payload
Payment states progress roughly as:
Treat approved as "paid and cleared" — that's the state at which funds are confirmed and screened. Failure branches include expired, underpaid, overpaid, wrong_asset, wrong_network, and screening_failed.
Delivery is retried up to 3 times with exponential backoff. Return any 2xx status to acknowledge; a non-2xx triggers a retry.
Verifying the signature
Every webhook for an API-created link is signed. Each request carries:
X-LFG-Timestamp— unix seconds.X-LFG-Signature—HMAC-SHA256(secret, "{timestamp}.{rawBody}"), hex-encoded.
The secret is the webhook signing secret you received when creating the API key. Recompute the HMAC over `${timestamp}.${rawBody}` and compare in constant time. Reject anything with a timestamp older than a few minutes to prevent replays.
Verify against the raw request body, exactly as received — before any JSON parsing or re-serialising. Re-encoding changes the bytes and breaks the signature.
Managing keys
API keys are created, listed, and revoked by the business owner in Settings → API Keys. You can have up to 5 active keys per business — rotate by creating a new key, then revoking the old one. Revoking takes effect immediately.
Integration checklist
Create an API key in Settings → API Keys; store the key and webhook secret in your backend.
Add a server endpoint that creates a payment link and returns the
checkoutUrl.Redirect the buyer to
checkoutUrl; setsuccessUrl/cancelUrlback to your site.Add a webhook endpoint that verifies the signature and marks the order paid on
approved.Go live — the API is production from day one; there is no separate test environment.
Last updated