Escrow API for Nigerian Marketplaces: Build Delivery-Based Releases

An escrow API for Nigerian marketplaces helps developers connect buyer payments to conditional seller releases. The difficult part is not displaying an “accept delivery” button. It is ensuring that funding, delivery evidence, disputes and payout execution agree before money moves.

For marketplaces selling physical goods, freelance services or equipment rentals, that means building an explicit release workflow rather than treating payment confirmation as permission to pay the seller.

This guide explains how to design that workflow with Paddle’s escrow, virtual accounts, ledgers and Nigerian payout capabilities. The architecture is illustrative: confirm supported escrow arrangements, API operations and partner requirements before implementing production money movement.

When to use an escrow API for Nigerian marketplaces

Use escrow when payment and fulfilment happen at different times, and seller access to funds depends on an agreed condition. A buyer might fund an order today, receive goods later and accept delivery before the marketplace initiates seller payment.

That differs from simply delaying an ordinary payout. An escrow product needs defined release conditions, a dispute process and an approved arrangement for holding and moving funds.

Before designing the integration, establish:

• Who funds the transaction and who receives the proceeds.
• What evidence makes an order eligible for release.
• Who can stop or authorise a release.
• What happens if delivery fails or the buyer disputes it.
• Which funding, refund and payout routes the provider supports.

Paddle is not a bank; banking services are provided by CBN-licensed partner banks. Confirm the contractual and operational structure for your use case with Paddle and qualified advisers. Calling a database balance “escrow” does not establish a compliant arrangement, and this guide is not legal advice.

Model the order and the money separately

A single order_status field cannot reliably describe both fulfilment and funds movement. An order can be delivered while payment remains unconfirmed, or accepted while a seller payout is still processing.

Maintain separate state machines.

Commercial state

Track fulfilment using states such as:

created → accepted_by_seller → dispatched → delivered → buyer_accepted

Add cancellation and dispute states where your business rules require them. Store the evidence and actor behind each transition, not just the latest label.

Financial state

Track the associated funds independently:

awaiting_funding → funded → release_authorised → payout_pending → paid

Include alternative paths for refund_pending, refunded and exceptions requiring review. These are suggested internal states, not Paddle API status names.

Store disputes as a separate release-blocking condition. This lets an order remain commercially delivered while its funds are unavailable for release.

Keep identifiers for the order, buyer, seller, funding transaction, escrow arrangement and payout attempt. Never use a human-readable order number as the only link between external payment events and internal records.

Confirm funding before enabling fulfilment

Paddle offers virtual accounts, including Nigerian NUBANs, which can support identifiable bank-transfer collection workflows. Confirm how collections can fund your approved escrow arrangement; do not assume every virtual-account payment automatically becomes escrowed funds.

Your backend should treat verified provider records—not a buyer’s screenshot or a browser callback—as the source of payment confirmation.

A robust funding handler should:

• Authenticate incoming notifications using the documented mechanism.
• Match the transaction to the intended order and currency.
• Validate the amount against the order’s funding requirement.
• Record the provider transaction reference uniquely.
• Update the local funding record and enqueue downstream work atomically.

Define policies for underpayments, overpayments and late transfers. An underpaid order should not become release-eligible merely because a payment arrived. An overpayment should enter an exception workflow rather than silently increasing the seller’s entitlement.

If a notification is delayed, use documented transaction-retrieval or reconciliation facilities to establish the payment’s status. Do not ask the buyer to pay again simply because your application has not received an event.

Make release authorisation a server-side decision

A release request should express intent, not directly trigger an unconditional transfer. Your server must evaluate the current order, funding and dispute records before authorising execution.

Typical release conditions include confirmed funding, qualifying delivery evidence, no active dispute and a verified seller destination. The applicable conditions should be defined in your marketplace terms and supported by the provider arrangement.

The following pseudocode describes an internal operation, not a Paddle endpoint:

begin database transaction
  lock order and escrow allocation
  require funding is confirmed
  require delivery acceptance is valid
  require no active dispute
  require seller destination is verified
  require releasable amount >= requested amount
  require release intent does not already exist

  reserve requested amount
  create release intent with unique reference
  write execution job to transactional outbox
commit

The lock or equivalent concurrency control matters. Buyer acceptance and a dispute submission can arrive almost simultaneously. Without serialisation, both requests could pass checks against stale data.

Use the same concurrency boundary for dispute creation and release authorisation. Also define the cutoff after which a newly opened dispute cannot automatically stop an already submitted payout.

Keep ledger entries aligned with obligations

Your ledger should explain what the marketplace owes each participant and which amounts remain restricted. A provider balance alone cannot explain whether money belongs to an unreleased order, a pending refund or a seller payout in progress.

Represent at least these categories in your internal ledger:

• Confirmed funding allocated to an order.
• Funds unavailable because fulfilment is incomplete or disputed.
• Amounts reserved for an authorised release.
• Seller payouts and buyer refunds awaiting confirmation.
• Completed movements and separately identified adjustments.

Use integer minor units rather than floating-point arithmetic. Preserve currency on every amount and prohibit cross-currency balancing without explicit conversion entries.

Keep accounting balanced through your double-entry model, and make corrections through linked compensating entries rather than overwriting history. Have your finance team validate the chart of accounts and posting rules for the approved arrangement.

Paddle offers ledgers, but confirm how their records map to your product’s order-level obligations and reconciliation needs.

Treat seller payout as a separate execution phase

After authorisation, execute the supported release and payout sequence. Paddle supports instant NIP payouts to 120+ Nigerian banks, but your application should still handle pending outcomes, failures and reconciliation exceptions.

Avoid marking an order financially complete when a transfer request is merely accepted. Distinguish submission from confirmed completion.

Persist the execution reference before making a network call. Use documented idempotency controls where available, and maintain your own unique release-intent constraint. A timeout means the result is unknown—not necessarily that execution failed.

Before retrying an ambiguous request, check its status through supported lookup or reconciliation mechanisms. Never launch an independent refund against money that may already have been paid out.

If a payout fails definitively, retain a clear record of the seller obligation. Whether you restore the amount to a releasable allocation or require operational review should follow the actual provider outcome and your approved workflow.

Production readiness checklist

Before enabling live delivery-based releases, test the whole lifecycle rather than only successful payouts.

1. Confirm product fit. Validate escrow eligibility, supported collection routes, release controls and refund mechanics with Paddle.
2. Document release rules. Specify acceptable delivery evidence, buyer acceptance and dispute handling. Confirm whether automatic release is supported before offering it.
3. Test concurrent actions. Submit acceptance and dispute requests together; ensure only a valid transition wins.
4. Replay payment events. Duplicate and out-of-order notifications must not duplicate funding or authorisation.
5. Simulate uncertain execution. Drop the response after payout submission and verify that recovery does not create another payout.
6. Restrict manual intervention. Apply role-based permissions, approval controls and immutable audit records to overrides.
7. Reconcile obligations. Compare order allocations, internal postings and provider records; investigate unresolved differences.
8. Prepare support views. Show evidence, references and a timestamped state history without exposing sensitive credentials or unnecessary personal data.

Monitor ageing funded orders, blocked releases, unresolved payouts and reconciliation exceptions. These queues give operations teams actionable work without turning support staff into an alternative payment-authorisation system.

Build it with Paddle

Paddle brings escrow, virtual accounts, ledgers and Nigerian payouts into a broader banking-as-a-service platform for African digital businesses. Start by validating your proposed holding and release arrangement, then build one complete path from confirmed funding to delivery acceptance and confirmed seller payout.

Keep provider interactions behind a small integration layer, and keep your release policy explicit in your own application. That separation makes the workflow easier to test, audit and extend.

Ready to scope your integration? Create a free account and read the API docs to check available operations and plan your implementation.