Virtual Account Reconciliation API for Nigerian Marketplaces: A Developer Guide

For teams evaluating a virtual account reconciliation API for Nigerian marketplaces, issuing account numbers is only the beginning. The harder problem is reliably connecting each bank transfer to the right buyer, order, and seller obligation—without crediting balances twice or marking unpaid orders as complete.

In Nigeria, virtual accounts with NUBAN account numbers let customers pay by bank transfer into an account associated with your application’s collection flow. Paddle provides virtual accounts alongside ledgers and instant NIP payouts to 120+ Nigerian banks, giving developers building blocks for collections and disbursements.

This guide focuses on the architecture around those building blocks: payment matching, event processing, exception handling, and reconciliation. Any data structures below are illustrative application designs, not Paddle API schemas.

Designing a virtual account reconciliation API for Nigerian marketplaces

Start by separating three concerns that often become tangled in a marketplace backend:

• Collection: Did money arrive, and into which virtual account?
• Allocation: Which customer or order should receive credit?
• Settlement: How much does each seller become entitled to receive, and when?

A confirmed collection does not automatically mean an order is fully paid. A fully paid order does not automatically mean the seller should receive an immediate payout. Returns, fulfilment rules, and your marketplace’s commercial terms can affect the next step.

Model these concerns independently. Your payments service records incoming transfers, your order service evaluates payment completion, and your ledger records the resulting financial obligations.

Paddle is a banking-as-a-service platform by Pickpadi Global Ltd, not a bank. Banking services are provided by CBN-licensed partner banks. Confirm the account structures, collection capabilities, and operating requirements available to your business before implementing the flow.

Choose the right virtual account mapping

Your matching strategy depends on what a virtual account represents inside your product.

Customer-level accounts

A persistent account associated with a customer can simplify repeat purchases. When a transfer arrives, you identify the customer using the receiving account and then allocate the funds according to an explicit rule.

The challenge is order ambiguity. If one customer has three unpaid orders, the account number alone does not identify which order they intended to pay. You need an allocation mechanism, such as a customer-selected order or an unapplied credit balance.

Avoid silently applying transfers to the oldest order unless that behaviour is clearly communicated and appropriate for your product.

Order-level accounts

An account associated with one order can make matching more direct, where that issuance model is supported. Your application maps the receiving account to a specific order and compares confirmed receipts with the expected total.

Before choosing this design, confirm account availability, lifecycle rules, expiry behaviour, and what happens to transfers received after an order closes. Do not assume every virtual account product supports disposable or expiring accounts.

For either model, store your mapping durably before displaying payment instructions to the customer.

Model payments separately from order status

Use distinct records for the account mapping, payment event, allocation, and ledger entry. This makes retries and investigations easier than storing everything in a single order row.

An illustrative internal payment record might look like this:

{
  "internal_payment_id": "pay_example_001",
  "provider_transaction_id": "provider_reference_here",
  "virtual_account_id": "account_reference_here",
  "customer_id": "customer_example_001",
  "order_id": null,
  "currency": "NGN",
  "amount_minor": 2500000,
  "processing_state": "received"
}

Use integer minor units for your internal monetary calculations. For NGN, that means kobo. Convert provider amounts according to the documented API representation; do not assume an external amount field uses your internal convention.

Treat the provider transaction reference as a reconciliation key, subject to its documented uniqueness scope. Your own payment identifier serves a different purpose: keeping application records stable across internal services.

Process payment notifications safely

Payment notifications should trigger a controlled processing workflow, not a direct instruction to fulfil an order.

Authenticate and persist before processing

Implement notification verification exactly as described in the current Paddle documentation. Do not invent signature headers or verification algorithms. If the integration requires checking transaction status through the API, perform that check before treating the transfer as confirmed.

A resilient ingestion flow is:

1. Verify the request using the documented mechanism.
2. Validate required fields and the expected account context.
3. Persist the event or enqueue it durably.
4. Return the documented acknowledgement promptly.
5. Process the financial update in a retryable worker.

Keep secrets on your server and restrict access to raw event payloads. Logs should help diagnose failures without unnecessarily exposing customer information.

Make financial updates idempotent

Design for repeated notifications and worker retries, even if they are uncommon during testing. The same transfer must never generate two customer credits.

Enforce a database uniqueness constraint using the provider’s documented transaction identifier and relevant scope. Within one database transaction, record the processed payment, create the allocation, and write the associated ledger entries.

If fulfilment happens in another service, publish an internal event through a transactional outbox or equivalent durable mechanism. This prevents a crash between committing the payment and notifying the order service from leaving the order stuck.

Handle mismatches without losing money trails

Exact payments are straightforward. The exception paths determine whether your implementation survives production.

Underpayments and overpayments

Compare the total confirmed amount allocated to an order with its payable amount. An underpayment should leave the order partially paid, rather than falsely complete.

For an overpayment, separate the order allocation from the excess. Route the excess into a clearly defined unapplied balance or refund workflow. Do not silently turn it into marketplace revenue.

Late and unmatched transfers

A transfer may arrive after cancellation or without enough information to identify an order. Record the money first, then place it in an exception queue with an owner and resolution status.

Support staff should resolve the allocation through an audited action, not by editing transaction amounts or deleting records. Preserve the original payment reference throughout the resolution.

Refunds and reversals

Refunds and reversals are separate financial events. Represent them with linked records and compensating ledger entries rather than overwriting the original collection. Confirm the provider’s supported processes and status meanings before automating either workflow.

Reconcile provider records, your ledger, and payouts

Webhooks support timely updates; reconciliation detects gaps. Run a scheduled process that compares available provider transaction records or statements against your internal payment records and ledger.

Check for:

• Provider-confirmed collections missing internally.
• Internal credits without a matching confirmed collection.
• Amount or currency mismatches.
• Unallocated receipts awaiting investigation.
• Seller payouts with unresolved status.

Choose a reconciliation interval that fits your transaction volume and operational needs. Maintain a cursor or checkpoint, and overlap query windows where appropriate so delayed records are not skipped.

Keep collection reconciliation separate from seller payout reconciliation. A seller’s payable balance should come from your ledger and release rules—not simply the total value of transfers into a virtual account.

Paddle’s NIP payout capabilities can support the disbursement stage, but your application still needs payout authorisation, duplicate prevention, status tracking, and a process for investigating exceptions.

Pre-launch implementation checklist

Before enabling bank-transfer checkout for real customers, verify that your team can:

• Trace a collection from receiving account to payment, order allocation, and ledger entries.
• Replay the same event without duplicating any financial effect.
• Recover from a worker crash after an event is persisted.
• Handle partial, excess, late, and unmatched payments.
• Reconcile a confirmed collection when its notification was missed.
• Prevent seller payouts from exceeding eligible payable balances.
• Resolve exceptions through access-controlled, audited actions.

Confirm applicable onboarding, account-use, and compliance requirements with your provider and qualified advisers. Check the latest CBN guidance where relevant; this architecture guide is not legal advice.

Build it with Paddle

Paddle brings virtual accounts, ledgers, and Nigerian bank payouts into a broader toolkit for African digital businesses. Start with one collection flow, make payment processing idempotent, and prove that your reconciliation process can recover missed events before adding more settlement complexity.

To assess the capabilities available for your marketplace, create a free account and read the API docs. Confirm the supported account lifecycle, notification verification, transaction lookup, and payout flows, then map them to your application’s payment and ledger model.