Bank Transfer Refund API for Nigerian Marketplaces: Build a Controlled Return Flow

A bank transfer refund API for Nigerian marketplaces should do more than send money back. It should connect a refund to its original collection, establish who should receive it, prevent over-refunding, and preserve evidence that finance and support teams can follow.

This becomes important when customers pay by bank transfer into virtual accounts. An order may be cancelled, an item returned, or a delivery only partially fulfilled. Unlike a card refund workflow, a refund funded through a new bank transfer should be treated as a separate payout—not an assumption that the original payment can simply be reversed.

For Nigerian marketplaces, the practical solution is a refund orchestration layer backed by verified collection records, a ledger, and NIP payout infrastructure. Here is how to design it before connecting the payment rails.

What a bank transfer refund API for Nigerian marketplaces must handle

The central challenge is separating three decisions:

• Eligibility: Does the customer have a valid refund entitlement?
• Destination: Which bank account is authorised to receive the money?
• Execution: Has the approved amount actually been paid out?

A successful collection does not automatically establish refund eligibility. An approved refund does not prove that its destination is safe. And an accepted payout request does not necessarily mean the recipient has been credited.

Keep these decisions distinct in your application. Your order system determines the commercial entitlement, your controls establish the destination, and your payments integration executes and tracks the transfer.

Paddle provides virtual accounts, ledgers, and instant NIP payouts to 120+ Nigerian banks. These capabilities can support the collection-to-refund lifecycle, while your marketplace retains responsibility for its refund policy and approval rules.

Anchor every refund to a confirmed collection

Start from the original payment record, not a screenshot or a customer-entered transaction reference alone.

Your refund service should retrieve the confirmed collection and its associated order, customer, currency, and amount. Where several payments fund one order, record which collection funds each refund allocation.

A useful refund record includes:

• Internal refund ID and original collection ID.
• Order ID, customer ID, and seller ID where applicable.
• Requested amount, approved amount, and currency.
• Reason code and supporting evidence references.
• Destination verification status and approval history.
• Payout reference and final outcome.

Keep customer-facing explanations separate from internal review notes. A customer needs to understand the refund decision, but should not receive sensitive fraud-review information.

Calculate refundable value under concurrency

Use a ceiling based on the original collection:

remaining refundable amount = collected amount − completed refunds − active refund reservations

An active reservation is an amount committed to a refund that has not reached a final outcome. Without this reservation, two agents could each approve a refund against the same available balance.

Create the reservation and validate the ceiling within one atomic database operation. Store naira amounts in integer kobo rather than floating-point values.

If your policy treats delivery charges or other components differently, calculate eligibility at the order-line level before applying the collection ceiling. Explain deductions clearly and review their appropriateness for your business.

Verify the recipient without creating an account-change loophole

Refund destination changes are a risk point. Someone who gains access to a customer account could request a legitimate refund but redirect the payment elsewhere.

Prefer returning funds to a verified original funding account when reliable account details are available and your policy permits it. Do not assume every collection notification contains enough information to identify that account safely.

If you must collect destination details, use a controlled process:

1. Require an authenticated refund request linked to the order.
2. Capture the bank and account number through a protected form.
3. Perform account-name verification through an available, documented verification service.
4. Compare the result with the customer and payment evidence.
5. Route mismatches, third-party payments, and changed destinations for review.
6. Require fresh approval if destination details change after approval.

An account-name match is useful evidence, not proof that the requester controls the account. Similarly, OTP can confirm access to a registered channel but does not independently prove bank account ownership.

Avoid sending full account numbers through support chat or exposing them in routine application logs. Mask sensitive details in operational screens and restrict access by role.

Separate refund entitlement from available cash

A marketplace can owe a refund even when the related seller proceeds have already been paid out. That creates a funding problem, not necessarily a reason to reject the customer's entitlement.

Model two separate questions:

• Is the refund approved under the marketplace's policy?
• Is the platform's payout balance funded to execute it?

For unsettled seller proceeds, your commercial arrangements may allow an adjustment before seller payment. For already-settled proceeds, you may need a seller receivable, an agreed reserve, or platform funding while recovery proceeds separately.

Have finance define the ledger treatment for these cases. Do not silently deduct a seller balance without the contractual basis and controls to support it.

Track refund payable, refund funds reserved, and refund paid as distinct events. A delayed funding step should remain visible rather than disappearing into a generic failed status.

Use a refund state machine above the payout rail

Keep the refund lifecycle separate from the underlying transfer lifecycle. A practical application-level sequence is:

requested → reviewing → approved → funds_reserved → payout_submitted → paid

Add exception states such as rejected, awaiting_funding, and payout_needs_review. These are suggested internal states, not Paddle API status names; map them to the actual responses and events documented for your integration.

Treat uncertain outcomes as unresolved

If a payout request times out, do not immediately release the reservation or create another transfer. The payment may have been accepted even though your application did not receive the response.

Retain the refund-to-payout association and investigate the existing transfer using documented status-checking mechanisms. Apply authenticated webhook handling and deduplicate incoming events according to the provider's documentation.

Only mark the refund paid when the payment rail supplies the appropriate success evidence. If a transfer is confirmed unsuccessful, decide whether to retry the same approved destination or request a reviewed correction.

For confirmed returns after an apparent completion, retain the original payment history and create a new exception event. Never erase the original payout to make the refund look unprocessed.

Give support and finance one evidence trail

A useful refund dashboard answers four questions: why the refund was approved, where it was sent, what its latest status is, and what action comes next.

Show support staff a customer-safe summary with masked destination details. Give finance access to the collection allocation, reservation, payout reference, and ledger movements. Record who changed the amount or destination and who approved execution.

Customer notifications should distinguish approval from payment completion. “Your refund has been approved” and “Your refund has been sent” describe different milestones. Avoid promising a fixed arrival time unless your operational commitments support it.

Reconcile completed refunds against both payout records and the internal ledger. Investigate missing links rather than treating a successful transfer alone as sufficient accounting evidence.

Pre-launch refund checklist

Before releasing the flow, test these scenarios:

• Two simultaneous partial refunds cannot exceed the original collection.
• An unconfirmed collection cannot fund an automatic refund.
• Changing the destination invalidates the previous approval.
• A payout timeout does not trigger a second payment.
• Duplicate or out-of-order events cannot duplicate ledger postings.
• Insufficient payout funds leave the approved liability visible.
• A failed transfer preserves the refund entitlement and audit history.
• A third-party payer case reaches an appropriate review queue.

Also define approval thresholds, access permissions, evidence retention, and escalation ownership. Review applicable Nigerian requirements with qualified advisers and check the latest relevant CBN circulars. This workflow is a product design guide, not legal advice.

Build it with Paddle

Paddle gives Nigerian marketplaces building blocks for a controlled refund flow: virtual accounts for collections, ledgers for money movement records, OTP for verification steps, and instant NIP payouts to 120+ Nigerian banks.

Build your eligibility rules, destination controls, and refund state machine around those capabilities. Confirm supported API fields, authentication requirements, event handling, and transfer-status behaviour before implementation.

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 connect your refund workflow to payment infrastructure? create a free account and read the API docs.