Flutterwave checkout links: references and expiry
How a Flutterwave Standard checkout runs for a Nigerian invoice, why every payment needs its own reference, and when a payment window closes.
By Achekam · · 4 min read · For Running a business businesses in Nigeria
A customer opens your invoice on their phone, taps the payment link and pays through Flutterwave. A moment later they are back where they started, with a confirmation. To the customer it is one smooth step. Behind it sit a handful of rules that decide whether the payment is matched to the right invoice, whether an old link still works, and whether "paid" really means paid.
Flutterwave calls this hosted checkout Flutterwave Standard. This article explains how it works, using Flutterwave's own documentation, and how Achekam's invoice pay links sit on top of it.
Server request, hosted page, redirect back
Flutterwave's documentation describes three steps. The merchant makes a server-side request to the create payment endpoint. It then redirects the customer to the payment-page link that Flutterwave returns. Once the transaction is completed, Flutterwave redirects the customer back to the merchant's site.
The detail that matters for a business is the first step: the payment is set up from your system, not typed in by the customer. The amount, the currency and the reference are fixed before the customer sees the page. The documentation adds that the currency defaults to NGN if none is given, and that a customer e-mail is required. You can read the full sequence on Flutterwave's Flutterwave Standard page, which shows how to create the payment details on your server, send the customer to the returned link and handle the redirect back.
A unique reference for every payment
Each Flutterwave Standard payment carries a reference the merchant generates, called tx_ref. Flutterwave's documentation says it must be unique for every transaction.
Uniqueness is what lets money find its invoice. If two payment attempts share a reference, a payment for one could be read as a payment for the other. If a reference is reused after a failed attempt, the history of that payment becomes confusing. A business that builds its own integration should generate a fresh reference for every attempt and store it against the invoice. A business using accounting software should check that the software does the same.
How long the window stays open
Flutterwave lets the merchant decide how long a customer has to finish paying. Its documentation says a merchant can set a checkout session_duration of up to 1440 minutes (24 hours), after which the payment window closes and uncompleted transactions are immediately cancelled and marked as failed. A max_retry_attempt setting works in the same spirit: once a customer exceeds the allowed retries, the transaction fails.
For your customers, that means a payment page left open overnight may no longer accept payment in the morning. That is a safety feature, not a fault. When a customer says "the link didn't work", the usual answer is to send a fresh one, not to ask them to keep trying the old page.
Switching off a link you no longer need
Sometimes a link should stop working before it expires on its own: the order was cancelled, the price changed, or the product was withdrawn. Flutterwave's documentation says merchants can disable payment links generated through Flutterwave Standard, for example when a product or service is delisted, by sending the link to the Disable payment link endpoint. Only Standard links can be disabled this way.
Achekam's pay links: lifetime and reuse
In Achekam, a business can create a payment link for an issued customer invoice, copy it, or e-mail it with the invoice, and the customer pays on a public page that shows the business's name and branding. A business can take Flutterwave payments on its invoices in ZAR, NGN, KES, GHS or USD.
A few rules shape those links:
- Only issued invoices get one. There is no link for a draft or a voided invoice. Issuing an invoice takes the next number in its sequence and posts it to the ledger as debtors, sales and output VAT, so the link always points at a real, numbered debt.
- Lifetime. A link lasts 14 days by default, and the business can set anything from 1 to 720 hours instead.
- Reuse. If an open link already exists for the same amount, it is reused rather than a second one being created, so a customer who receives two reminders is not paying against two different requests.
The choices of provider for naira invoices are compared in collecting naira payments, and connecting your own Flutterwave keys is covered in setting up your payment gateway.
Verifying before the invoice is marked paid
Flutterwave's documentation says that after a Flutterwave Standard payment the merchant should handle the redirect on its server and always verify the final state of the transaction. A customer arriving back on your site is not proof of payment; the redirect can happen after a failed or abandoned attempt too.
Achekam follows that rule. Each Flutterwave payment is re-verified with Flutterwave before it is recorded. A verified payment is then recorded as a receipt against the invoice, debiting the Flutterwave clearing account and crediting trade receivables, and the invoice shows as paid or part-paid. The amount is checked against what the link asked for, and a repeated notification never pays twice. The money goes from the customer's payment to the ledger without anyone retyping it.
Points for whoever answers customer calls
- "The link has expired." Send a new link from the invoice rather than reusing the old page.
- "I paid but the invoice still shows unpaid." Check the provider's record first; a payment that never completed was never received.
- "I paid twice." Look up both references; only verified payments count, and a repeated notification for one payment is not recorded twice.
- "The amount is wrong." Void the invoice if nothing has been paid on it, or credit it, and issue the correct one, so the new link carries the right amount.
Most payment queries are answered by the reference. Keep it visible on every receipt and statement you send.
General guidance only, not advice on your own circumstances. Tax and payroll rules change: check the current position with the authority or your adviser.
