> ## Documentation Index
> Fetch the complete documentation index at: https://vouch-sdk.vercel.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Nomba Payment Infrastructure

> How Vouch uses Nomba virtual accounts, webhook reconciliation, and automatic overpayment refunds to power escrow funding.

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

```typescript theme={null}
const agreement = await vouch.escrow.create({ ... });

// Show the buyer where to send payment
console.log(agreement.nombaVirtualAccountNo); // e.g. "9988771122"
console.log(agreement.nombaBank);             // "Nomba MFB"
```

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](/docs/resources/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:

| Running total                   | Agreement status |
| ------------------------------- | ---------------- |
| Below `totalAmount`             | `PARTIAL`        |
| Equal to or above `totalAmount` | `FUNDED`         |
| More than `totalAmount × 1.01`  | `OVERFUNDED`     |

***

## 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.

```typescript theme={null}
await vouch.escrow.confirm(agreementId, milestoneId, externalUserId, {
  sellerAccountNumber: '0123456789',
  sellerBankCode: '058',
});
```

A final fraud assessment runs on the seller before every disbursement. If the result is `RED`, the agreement is frozen and disbursement is blocked.