Vouch SDK Escrow: Create and Manage Payment Agreements

The escrow module orchestrates structured payment agreements between a buyer and a seller. You break a transaction into milestones, Vouch holds the funds, and disbursement happens only after both parties confirm each milestone. The module also runs a fraud assessment at the payment step, so you catch bad actors before funds are ever collected. There are four methods in the escrow module: create, assess, confirm, and status.

`vouch.escrow.create(params)`

Create a new escrow agreement by specifying the parties, the total amount, and the milestone breakdown. Vouch returns an agreement record including an ID you will use in all subsequent calls.

import Vouch from 'vouch-sdk';

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

const agreement = await vouch.escrow.create({
  buyerExternalId: 'buyer-001',
  sellerExternalId: 'seller-042',
  totalAmount: 500000,
  currency: 'NGN',
  milestones: [
    { title: 'Design mockups', amount: 150000 },
    { title: 'Frontend implementation', amount: 200000 },
    { title: 'Final delivery & handover', amount: 150000 },
  ],
  buyerEmail: 'buyer@example.com',
  buyerName: 'Amara Obi',
});

console.log('Agreement ID:', agreement.id);
console.log('Pay into:', agreement.nombaVirtualAccountNo, '@', agreement.nombaBank);

Parameters

string

required

Your platform’s unique identifier for the buyer — the party that will fund the escrow.

string

required

Your platform’s unique identifier for the seller — the party that will receive disbursements.

number

required

The total agreement value in the base currency unit (e.g., kobo for NGN). Must equal the sum of all milestone amounts.

string

ISO 4217 currency code. Defaults to "NGN".

{ title: string; amount: number }[]

required

An ordered array of milestone objects. Each milestone has a title (descriptive label) and an amount (in base currency units). Disbursement is unlocked per milestone as both parties confirm.

string

Optional email address for the buyer. Vouch may use this for payment instructions and notifications.

string

Optional display name for the buyer, used in communication and agreement records.

Response fields

string

The Vouch-assigned unique identifier for this agreement. Store this — you need it for assess, confirm, and status calls.

string

The developer account ID associated with this agreement.

string

The buyer ID you supplied, echoed back for confirmation.

string

The seller ID you supplied, echoed back for confirmation.

string

Current lifecycle status of the agreement. See the status reference at the end of this page.

string | null

The Nomba-assigned virtual account holder ID for this agreement. May be null until provisioning completes.

string | null

The NUBAN (Nigerian Uniform Bank Account Number) the buyer should transfer funds into. Display this to the buyer after creating the agreement.

string | null

The receiving bank name — typically "Nomba MFB". Display alongside nombaVirtualAccountNo so the buyer knows where to send payment.

number

Total agreement value in base currency units.

string

Currency code for the agreement.

string

ISO 8601 timestamp of when the agreement was created.

object[]

The milestone records associated with the agreement.

Show milestone fields

string

Vouch-assigned unique identifier for the milestone. Use this in confirm calls.

string

Descriptive label for the milestone.

number

Value of this milestone in base currency units.

boolean

Whether the buyer has confirmed this milestone as complete.

boolean

Whether the seller has confirmed this milestone as complete.

string

The current status of this individual milestone (e.g., PENDING, CONFIRMED, DISBURSED).

`vouch.escrow.assess(agreementId, params)`

Before collecting funds, run a fraud assessment tied to the agreement. If the assessment passes, Vouch returns a virtual account number the buyer can pay into.

const fundingCheck = await vouch.escrow.assess(agreement.id, {
  externalUserId: 'buyer-001',
  transactionAmount: 500000,
});

if (fundingCheck.flag === 'RED') {
  // Block this payment attempt
  throw new Error('Payment blocked due to high fraud risk.');
}

if (fundingCheck.virtualAccount) {
  const { accountNumber, bankName, accountName } = fundingCheck.virtualAccount;
  console.log(`Pay to: ${accountName} — ${accountNumber} @ ${bankName}`);
}

How funding works: Once the buyer transfers to the Nomba virtual account number, Nomba fires a virtual_account.funded webhook to Vouch automatically. Vouch reconciles the payment, updates the agreement status, and handles partial payments and overpayments — no polling required from your side.

Parameters

string

required

The ID of the agreement returned by vouch.escrow.create().

string

required

Your platform’s identifier for the user initiating payment (typically the buyer).

number

required

The amount being assessed in base currency units. This should match the agreement’s totalAmount or the milestone amount being funded.

boolean

Force a VPN detection signal. Sandbox and testing use only.

boolean

Force an impossible travel signal. Sandbox and testing use only.

Response fields

number

Fraud risk score from 0 to 100.

string

"GREEN", "AMBER", or "RED". See the fraud flag reference in the Fraud guide.

object

Nomba virtual account payment details for the buyer. Only returned on GREEN or AMBER responses.

Show virtualAccount fields

string

The Nomba NUBAN the buyer should pay into.

string

The receiving bank name, e.g. "Nomba MFB".

string

The account holder name associated with the virtual account.

The virtualAccount object is only included in the response when the fraud flag is GREEN or AMBER. A RED flag response will not contain payment details — block the session and do not prompt the user to pay.

`vouch.escrow.confirm(agreementId, milestoneId, externalUserId)`

Confirm that a milestone has been completed. Both the buyer and the seller must call this method for the same milestone before Vouch will release the corresponding funds to the seller.

// Called from the buyer's session
await vouch.escrow.confirm(
  agreement.id,
  agreement.milestones[0].id,
  'buyer-001'
);

// Called from the seller's session
await vouch.escrow.confirm(
  agreement.id,
  agreement.milestones[0].id,
  'seller-042'
);

console.log('Milestone confirmed by both parties — disbursement initiated.');

string

required

The ID of the escrow agreement.

string

required

The ID of the milestone to confirm, from the milestones[] array on the agreement.

string

required

Your platform’s identifier for the user confirming the milestone. Pass the buyer ID when confirming from the buyer’s side, and the seller ID from the seller’s side.

Both parties must confirm independently. Calling confirm from only one side records that party’s confirmation but does not trigger disbursement. Disbursement happens automatically once Vouch records confirmation from both buyerExternalId and sellerExternalId.

`vouch.escrow.status(agreementId)`

Fetch the current state of an agreement, including the latest milestone statuses and confirmation flags. The response shape is identical to the one returned by create.

const agreement = await vouch.escrow.status('agr_abc123');

console.log('Agreement status:', agreement.status);

for (const milestone of agreement.milestones) {
  console.log(`${milestone.title}:`);
  console.log(`  Buyer confirmed: ${milestone.buyerConfirmed}`);
  console.log(`  Seller confirmed: ${milestone.sellerConfirmed}`);
  console.log(`  Status: ${milestone.status}`);
}

The response is the same AgreementResponse object returned by create. Refer to the create response fields section above for full field documentation.

Agreement status reference

Status	Meaning
`PENDING`	Agreement created, no funds received yet.
`PARTIAL`	Buyer has sent a partial payment. Vouch is accumulating payments until the full amount is reached.
`FUNDED`	Full amount received and held in escrow. Work can begin.
`OVERFUNDED`	Payment exceeded the agreed amount by more than 1%. Vouch automatically attempts to refund the excess to the sender’s bank account.
`IN_PROGRESS`	At least one milestone disbursement has been made.
`COMPLETED`	All milestones confirmed by both parties.
`DISBURSED`	All milestone funds released to the seller. Terminal state.
`REFUNDED`	Funds returned to the buyer. Terminal state.
`FROZEN`	Agreement locked by a fraud signal. Terminal state — contact support.

Vouch reconciles payments via Nomba webhooks. Each bank transfer increments amountReceived — the agreement moves from PARTIAL to FUNDED automatically once the running total meets totalAmount. Do not allow the seller to begin work until the status is FUNDED.

Get Started

Core Concepts

SDK Reference

Guides

Resources

Vouch SDK Escrow: Create and Manage Payment Agreements

`vouch.escrow.create(params)`

Parameters

Response fields

`vouch.escrow.assess(agreementId, params)`

Parameters

Response fields

`vouch.escrow.confirm(agreementId, milestoneId, externalUserId)`

`vouch.escrow.status(agreementId)`

Agreement status reference

​vouch.escrow.create(params)

​Parameters

​Response fields

​vouch.escrow.assess(agreementId, params)

​Parameters

​Response fields

​vouch.escrow.confirm(agreementId, milestoneId, externalUserId)

​vouch.escrow.status(agreementId)

​Agreement status reference

`vouch.escrow.create(params)`

Parameters

Response fields

`vouch.escrow.assess(agreementId, params)`

Parameters

Response fields

`vouch.escrow.confirm(agreementId, milestoneId, externalUserId)`

`vouch.escrow.status(agreementId)`

Agreement status reference