Multi-currency card refund reconciliation in Nigeria: A Product and Ledger Guide

Multi-currency card refund reconciliation in Nigeria is a critical workflow for fintechs building cards funded from naira balances. The purchase may be priced in one currency, billed in another and refunded after exchange rates have moved. Without clear accounting rules, a successful merchant refund can still become a balance dispute.

For founders, product leaders and developers, the challenge is bigger than displaying a credit. You need to identify what happened, determine what the customer is owed and explain any difference without losing the audit trail.

This guide focuses on the post-purchase lifecycle: reversals, refunds, FX differences and reconciliation. Paddle provides card issuing through licensed partners, real-time FX and ledgers as building blocks. Confirm the exact programme currencies, refund events and settlement behaviour with Paddle before designing your production flow.

Why refunds need their own product design

A card purchase is not always one debit followed by one matching credit. An authorisation can reserve funds before a transaction clears. A merchant might cancel before clearing, issue a partial refund later or submit multiple refunds against one purchase.

These events have different meanings:

• Authorisation reversal: releases some or all of a reservation; it is not necessarily a new incoming payment.
• Cleared refund: creates a credit after the original purchase has cleared.
• Dispute-related credit: belongs to a separate dispute process and may be provisional.

Treating all three as “refund received” can inflate available balances or make transaction histories misleading.

For a Nigerian business offering international card spend, the key product question is: which balance is the customer entitled to receive, and when does it become available? Answer that before implementing the interface.

Multi-currency card refund reconciliation in Nigeria: the accounting model

Start by separating the currencies involved. Depending on the card programme, these may include:

• Merchant currency: the currency in which the purchase was presented.
• Card billing currency: the currency used to bill the card account.
• Customer wallet currency: the balance the customer uses to fund or receive value.
• Settlement currency: the currency used for settlement with the relevant partner.

Some programmes collapse these into one or two currencies. Others do not. Never assume the amount shown on a merchant receipt is the amount posted to your funding ledger.

Store amounts with their context

For every purchase and refund, preserve each amount and currency supplied by the programme. Where available, retain the original transaction reference, refund reference, settlement reference and relevant processing timestamps.

Also record your own funding conversion separately from the card transaction. If a customer converts naira into a foreign-currency wallet before spending, that conversion is not the same economic event as the purchase.

Use currency-aware fixed-point arithmetic, not floating-point arithmetic. Record the applicable precision and rounding rule for every currency you support.

Make the FX policy explicit

There are several possible customer experiences:

• Return the refund to the original foreign-currency balance.
• Convert the received refund into naira under a disclosed conversion policy.
• Restore the original naira debit, with the business absorbing or retaining the difference where permitted and transparently disclosed.

Do not choose solely for interface simplicity. The policy must fit the partner programme, your accounting model and applicable obligations.

If you promise the original naira amount back, you are taking on exposure that may not be covered by the actual refund proceeds.

Separate lifecycle state from money movement

A merchant saying “refund issued” does not necessarily mean your platform has received spendable funds. Your internal model should distinguish notification, processing and posted value.

An illustrative application-level lifecycle is:

observed → awaiting_confirmation → posted → reconciled

Maintain a separate exception status for cases that cannot progress automatically. These labels are design suggestions, not Paddle API statuses; map them to the documented events and reports available for your programme.

Handle duplicate and out-of-order events

Make event processing idempotent using a stable provider event identifier where available. Add controls against duplicate financial postings, because multiple event types may refer to the same refund.

Store incoming events before processing them, verify their authenticity using the provider’s documented mechanism and retain enough information for safe replay.

A refund may arrive before your system has ingested the corresponding cleared purchase. Send unmatched records to an exception queue rather than guessing a match from amount and merchant name.

Support partial refunds as separate records

Do not overwrite a purchase with its remaining net value. Keep the original purchase and each refund as separate records, then calculate totals for display.

A partial refund should be linked to the purchase without erasing the original debit. Flag unexpected cumulative refund amounts for investigation, but do not discard a genuine financial event simply because it violates an application assumption.

Post ledger entries that explain the difference

Your operational ledger should make the source and destination of value visible. Use balanced entries within each currency and explicit accounts to represent conversions between currencies.

A useful account structure distinguishes:

• Customer available balances.
• Reserved or held balances.
• Partner settlement or clearing balances.
• Refund suspense balances for unresolved items.
• FX differences and any separately applicable fees.

The exact chart of accounts depends on your legal and accounting structure. Have a qualified accounting professional review it before launch.

Keep conversion and refund postings distinct

Consider an illustrative purchase billed at USD 100, funded through a prior naira conversion. Later, the merchant refunds USD 40.

If the programme credits USD 40 and your policy returns dollars to the customer’s dollar balance, that refund does not require a naira conversion. If your policy instead returns naira, record the USD refund and subsequent conversion as separate linked events.

The naira value may differ from the corresponding share of the original funding debit. Attribute that difference to its actual source rather than hiding it inside an unexplained adjustment.

Never assume purchase fees are refundable. Only reverse a fee when the programme terms and your customer policy support doing so.

Reconcile against more than your webhook log

Webhooks support timely updates, but they should not be your only reconciliation source. Compare your event history and ledger postings with the partner transaction and settlement records available to your programme.

Run reconciliation at three levels:

• Transaction: Does each refund match a recognised external record and the correct purchase where a linkage exists?
• Ledger: Did it produce the intended balanced postings exactly once?
• Settlement: Do aggregate credits, debits and adjustments agree with the relevant settlement records?

Explain timing differences separately from true mismatches. A posted customer credit and partner settlement may follow different schedules under the programme.

Give every exception an owner, reason code and resolution history. Manual corrections should use authorised compensating entries, not edits that erase previous postings.

Launch checklist for a Nigerian card product

Use this checklist before enabling refunds in production:

1. Confirm programme behaviour. Verify supported currencies, event coverage, transaction links, refund restrictions and settlement reporting.
2. Document the customer policy. Explain refund currency, FX treatment, fee treatment and when value becomes available.
3. Define the posting rules. Separate hold releases, cleared refunds, conversions and dispute-related credits.
4. Test difficult sequences. Cover partial refunds, duplicates, delayed events, unmatched purchases and refunds to closed or restricted accounts.
5. Validate reconciliation. Demonstrate that transaction records, ledger entries and settlement records can be traced end to end.
6. Prepare support tools. Show agents the original purchase, refund status, credited amount and any separate conversion.
7. Review compliance boundaries. Confirm responsibilities with your partners and advisers, and check the latest applicable CBN circulars and other requirements.

This is a product and engineering checklist, not legal advice. Avoid promising a universal refund deadline unless your programme supports it.

Build it with Paddle

Paddle brings together card issuing through licensed Mastercard/Visa partners, real-time FX and ledgers for African digital businesses. These capabilities can support a card product where refunds, conversions and customer balances remain traceable rather than becoming manual spreadsheet work.

Start by validating your proposed refund policy against the available card programme and integration interfaces. Then map your purchase, refund and conversion records to documented identifiers and build reconciliation before expanding access.

Paddle is a banking-as-a-service platform by Pickpadi Global Ltd, not a bank. Banking services are provided by CBN-licensed partner banks; card issuing is provided through licensed partners.

Ready to scope your integration? Create a free account and read the API docs.