Nomba Webhook Events & Payment Reconciliation

Vouch uses a webhook-driven payment reconciliation model. When a buyer transfers funds into a Nomba Virtual Account, Nomba fires a virtual_account.funded event directly to the Vouch backend. Vouch validates the signature, reconciles the payment, and advances the escrow state machine automatically — no polling or manual confirmation needed from your integration.

How It Works

Buyer transfers funds
        │
        ▼
 Nomba Virtual Account
        │
        ▼
 Nomba fires POST → /escrow/webhooks/nomba
        │
        ├─ Signature verified (HMAC-SHA256)
        ├─ 200 acknowledged immediately
        └─ Async reconcile:
              ├─ Match account number → Agreement
              ├─ Idempotency check (nombaReference unique)
              ├─ Accumulate amountReceived
              ├─ Derive new status (PARTIAL / FUNDED / OVERFUNDED)
              ├─ Auto-refund excess if OVERFUNDED
              └─ Advance escrow state machine

You do not need to register or configure anything for this to work. The webhook endpoint is already configured on the Nomba dashboard for your sub-account.

Signature Verification

Every incoming Nomba request is signed with HMAC-SHA256 over the raw request body, delivered in the nomba-signature header. Vouch verifies this before processing any event — requests with a missing or mismatched signature are rejected with 401.

The signature is computed over the raw request bytes. The Vouch backend applies express.raw() middleware to this route to prevent JSON parsing from modifying the body before the signature check.

Supported Event Types

Event Type	Handled
`virtual_account.funded`	✅ Fully handled — triggers reconciliation
All other types	Acknowledged and ignored

Partial Payments

If a buyer sends multiple transfers that collectively equal the agreed amount, Vouch handles it automatically. Each virtual_account.funded event increments the running amountReceived total:

`amountReceived` vs `totalAmount`	Status
`amountReceived < totalAmount`	`PARTIAL`
`amountReceived >= totalAmount`	`FUNDED`
`amountReceived > totalAmount × 1.01`	`OVERFUNDED`

Your integration only needs to watch for FUNDED before allowing work to begin. You do not need to track individual transfers.

Overpayment Handling

When the accumulated amountReceived exceeds totalAmount by more than 1%, Vouch:

Sets the agreement to OVERFUNDED
Calculates excess = amountReceived - totalAmount
Reads the sender’s bank details from the webhook payload
Immediately calls the Nomba transfer API to refund the excess to the original sender
Logs the outcome in your developer audit log as OVERPAYMENT_FLAGGED

Automatic refunds require the sender’s account number and bank code to be present in the Nomba webhook payload. If these details are missing, the refund is skipped and logged with a reason — you can handle it manually from the developer dashboard.

Idempotency

Every Nomba event carries a unique requestId. Vouch stores this as nombaReference on the transfer record, which has a database-level unique constraint. If Nomba retries a delivery (common in production), the duplicate is detected and silently dropped — the agreement is never double-credited.

Developer Audit Log Events

Every reconciliation writes a structured entry to your developer log, visible in the dashboard:

`eventType`	When
`RECONCILIATION_MATCHED`	Payment matched and `amountReceived` updated
`OVERPAYMENT_FLAGGED`	Payment exceeded tolerance; automatic refund attempted
`ESCROW_FUNDED`	Agreement advanced to `FUNDED`
`ESCROW_FUND_FAILED`	An error occurred during state machine advancement

Polling as a Fallback

If you need to check agreement status from your frontend or in a background job, use vouch.escrow.status() at any time:

import Vouch from 'vouch-sdk';

const vouch = new Vouch('your-api-key');

const agreement = await vouch.escrow.status('agr_abc123');
console.log(agreement.status); // 'PENDING' | 'PARTIAL' | 'FUNDED' | ...

For waiting on payment confirmation, a lightweight polling loop with a 5-second interval is a reliable approach for most bank transfer windows:

async function waitForFunding(agreementId: string, maxAttempts = 24) {
  for (let i = 0; i < maxAttempts; i++) {
    const agreement = await vouch.escrow.status(agreementId);
    if (['FUNDED', 'OVERFUNDED'].includes(agreement.status)) {
      return agreement;
    }
    await new Promise(r => setTimeout(r, 5000)); // wait 5 seconds
  }
  throw new Error('Funding timeout after 2 minutes');
}

For instant bank transfers (NIP), a 5-second poll interval over 24 attempts covers a 2-minute window — enough for the vast majority of payments. For manual transfers, consider a longer window or a user-triggered re-check button.

Get Started

Core Concepts

SDK Reference

Guides

Resources

Nomba Webhook Events & Payment Reconciliation

How It Works

Signature Verification

Supported Event Types

Partial Payments

Overpayment Handling

Idempotency

Developer Audit Log Events

Polling as a Fallback

​How It Works

​Signature Verification

​Supported Event Types

​Partial Payments

​Overpayment Handling

​Idempotency

​Developer Audit Log Events

​Polling as a Fallback

How It Works

Signature Verification

Supported Event Types

Partial Payments

Overpayment Handling

Idempotency

Developer Audit Log Events

Polling as a Fallback