Skip to main content
Vouch’s escrow funding is powered by Nomba — a Nigerian fintech infrastructure provider. When an escrow agreement is created, Vouch provisions a dedicated Nomba Virtual Account (a real NUBAN bank account number) that the buyer transfers funds into via any standard bank transfer.

​
Virtual Account Provisioning

Every escrow agreement gets its own unique Nomba Virtual Account. When you call vouch.escrow.create(), Vouch:
  1. Creates the agreement and milestone records in the database
  2. Calls the Nomba API to provision a virtual account tied to the agreement ID
  3. Returns the NUBAN and bank name in the response
The virtual account has no expiry — it stays open until the agreement is funded, so buyers can complete payment at any time without the account expiring.

​
Webhook-Driven Reconciliation

Once the buyer transfers funds, Nomba fires a virtual_account.funded event to Vouch. Vouch:
  • Validates the HMAC-SHA256 signature on the raw request body
  • Acknowledges the request immediately (200) to prevent Nomba retries
  • Reconciles the payment asynchronously — matching the credited account number to the correct agreement
  • Increments the amountReceived running total
  • Derives the new agreement status (PARTIAL, FUNDED, or OVERFUNDED)
  • Emits an internal event to advance the escrow state machine
See Webhooks for the full reconciliation reference.

​
Partial Payment Support

Buyers can send funds in multiple transfers. Each bank transfer triggers a separate virtual_account.funded event, and Vouch accumulates them:

​
Automatic Overpayment Refunds

If a buyer sends more than 1% above the agreed amount, Vouch automatically initiates a refund of the excess back to the sender’s bank account via the Nomba transfer API — no manual intervention required.

​
Milestone Disbursement

When both buyer and seller confirm a milestone, Vouch calls the Nomba transfer API to send the milestone amount directly to the seller’s bank account. The seller provides their account number and bank code at confirmation time — Vouch does not store seller bank details before disbursement.
A final fraud assessment runs on the seller before every disbursement. If the result is RED, the agreement is frozen and disbursement is blocked.