FX quote expiry handling for Nigerian fintechs: A Conversion Flow Guide

FX quote expiry handling for Nigerian fintechs is a critical part of building a trustworthy currency conversion experience. A customer sees a rate, reviews the amount and taps confirm—but the quote may expire before your server receives the request. Without explicit rules, your product can execute an unexpected conversion, reserve funds indefinitely or report failure while money is still moving.

For Nigerian digital businesses offering currency conversion alongside global accounts or international payments, the solution is not simply a longer countdown. It is a controlled workflow that separates indicative pricing, customer consent, funds availability and confirmed execution.

This guide explains how to design that workflow and where Paddle’s real-time FX capabilities fit. Exact quote guarantees, supported corridors and execution behaviour should be confirmed during integration rather than inferred from the interface.

Why an FX quote needs its own lifecycle

A displayed exchange rate and an executable quote are not necessarily the same thing.

An indicative rate helps a customer estimate value. An executable quote, where supported, represents specific conversion terms subject to a validity window and other conditions. Neither should be treated as proof that a conversion has completed.

For example, a business user may open a conversion screen, switch to another app for approval, then return to confirm. Meanwhile, the rate, available balance or account eligibility may have changed.

Your product must answer three separate questions:

• What terms did the customer see and accept?
• Were those terms still executable when acceptance was processed?
• What conversion, if any, actually completed?

Store the evidence for each answer. A screenshot or browser countdown cannot substitute for a server-side transaction record.

FX quote expiry handling for Nigerian fintechs: Define the state machine

Model the quote separately from the conversion operation. Combining both into a single pending status makes support, retries and reconciliation unnecessarily difficult.

Quote states

A practical internal quote model can include:

• Active: Available for acceptance under its stated conditions.
• Expired: No longer available for acceptance.
• Superseded: Replaced by a newer quote in your application.
• Accepted: Linked to a conversion instruction that your system has recorded.

Acceptance in your database is not a guarantee of provider execution. Preserve that distinction in both naming and customer messaging.

Conversion states

Track execution with a separate operation record:

• Created: The customer’s instruction has been recorded.
• Submitted: The execution request has been sent.
• Processing: A final outcome is not yet available.
• Completed: Authoritative confirmation of success has been received.
• Failed: A definitive unsuccessful outcome has been established.
• Unknown: Communication failed and the execution outcome needs investigation.

These are suggested application states, not documented Paddle API status values. Map them to the actual API contract during implementation.

An expired quote must never overwrite a conversion that was already submitted. Once execution begins, resolve the operation’s outcome rather than treating quote expiry as cancellation.

Make rate acceptance explicit

Before confirmation, show the source currency, destination currency, source debit and expected destination credit. Identify any applicable fees and explain whether the displayed rate is indicative or executable.

For a Nigerian product, write currency labels clearly. Do not rely on a currency symbol alone when customers can hold multiple balances.

The confirmation view should make these details easy to scan:

• Amount the customer will pay.
• Amount the customer will receive, or a clear estimate where appropriate.
• Applicable charges and how they affect those amounts.
• Quote validity or refresh requirements.
• What happens if the quote expires before acceptance.

Avoid silently accepting a replacement quote. A changed rate can alter either the debit or the credit, depending on whether the customer specified a source amount or a destination amount.

A safer default is to display the refreshed terms and require confirmation again. If your product supports pre-authorised rate tolerances, define them explicitly, obtain appropriate consent and confirm that the provider supports the intended execution model.

Enforce expiry on the server

A browser countdown is a usability feature, not an authority. Devices have inaccurate clocks, tabs sleep and requests arrive late.

Your backend should validate quote ownership, expiry and acceptance eligibility using trusted timestamps. Preserve the provider’s expiry value where supplied, and synchronise your infrastructure clocks.

You can introduce a conservative local acceptance cutoff to reduce requests sent near expiry. However, a buffer does not extend the provider’s validity window or guarantee execution. The provider’s contract determines whether validity is checked at receipt, acceptance or another processing stage.

Never invent a guaranteed validity period because your frontend needs a timer. If the integration only supplies indicative rates, label them accordingly and establish how final pricing is accepted.

Handle simultaneous confirmation attempts

Customers double-tap buttons. Mobile clients retry requests. Two browser tabs can submit the same instruction.

Use an atomic state transition or database lock to prevent the same quote from creating multiple conversion operations. Add a unique constraint around your business-level acceptance reference.

If provider idempotency is available, follow its documented scope and retention rules. A locally unique reference does not automatically prevent duplicate execution at an external service.

Reserve funds without creating stranded balances

Rate validity and funds availability are separate checks. A valid quote cannot make an insufficient balance spendable.

Where your architecture requires a reservation, create it atomically with the internal acceptance record. Confirm the customer’s available balance, reserve the intended debit and link the reservation to the conversion operation.

Avoid holding a database transaction open while waiting on a network call. Persist the instruction durably, then use a controlled worker or equivalent delivery mechanism to submit it.

For products where the provider performs the debit atomically, align your internal accounting with that behaviour. Do not accidentally reserve or debit the same funds twice across application and provider layers.

Use decimal arithmetic or integer minor units appropriate to each currency. Define rounding rules for rates, fees and final amounts; binary floating-point calculations can introduce avoidable discrepancies.

Release a reservation after definitive failure or another verified safe condition. Do not release it merely because a request timed out: the conversion may still complete.

Recover safely from timeouts and late events

A timeout means your application did not receive a response. It does not prove the provider rejected the conversion.

When an execution request times out, retain the operation reference and show a processing message. Query the documented status mechanism before attempting another execution. Where webhooks are supported, verify their authenticity and process repeated deliveries idempotently.

Build handlers that tolerate events arriving out of order. A late processing event should not downgrade a completed conversion.

Also reconcile operations that remain unresolved beyond your normal processing window. Compare provider records, internal operation records and balance movements before deciding whether to release funds or escalate.

Customer support should see the quote reference, accepted terms, execution reference, reservation status and latest verified outcome. Avoid asking customers to repeat a conversion while the first attempt remains uncertain.

Practical pre-launch checklist

Test failure paths as deliberately as successful conversions:

1. Confirm the contract. Establish supported currencies, quote type, expiry semantics, execution rules, status lookup and idempotency behaviour.
2. Test boundary timing. Submit just before and after expiry, including delayed requests and inaccurate client clocks.
3. Test duplicate acceptance. Send simultaneous confirmations from separate sessions and verify that only one operation is created.
4. Test balance contention. Attempt a conversion while another transaction spends from the same balance.
5. Simulate uncertain outcomes. Drop the execution response and verify that recovery checks status instead of blindly resubmitting.
6. Verify accounting. Check successful debits and credits, failed-operation releases, rounding and unresolved reservations.
7. Review customer messaging. Ensure refreshed terms require appropriate consent and processing is not labelled as failure.

Track expired acceptance attempts, duplicate submissions, unresolved operations and reservation age. These operational signals help identify friction without assuming every issue is caused by exchange-rate movement.

For Nigeria, confirm applicable onboarding, transaction-purpose and FX requirements with your compliance team and relevant partners. Check current CBN guidance where applicable. This is an implementation guide, not legal advice.

Build it with Paddle

Paddle provides real-time FX, global accounts and global payouts that African digital businesses can use when designing connected financial workflows. Start by confirming availability, permissions and the exact pricing-to-execution contract for your intended currency corridor.

Keep customer consent, internal reservations and execution recovery explicit even when the provider handles the underlying conversion. Paddle is a banking-as-a-service platform by Pickpadi Global Ltd, not a bank; banking services are provided by CBN-licensed partner banks.

Ready to develop your conversion flow? create a free account and read the API docs to plan your integration with Paddle.