Create an Escrow Agreement — Vouch API

The Create Agreement endpoint initialises a new escrow contract between two parties identified by your platform’s own user IDs. You supply the buyer and seller external IDs, a total amount, and an array of milestones that define how funds will be released in stages. Vouch returns a fully formed agreement object in PENDING status — funding can begin once you run a payment risk assessment against it.

Endpoint

POST /v1/escrow/agreements

Request

Headers

string

required

Your Vouch API key. All protected routes require this header.

Body Parameters

string

required

Your platform’s unique identifier for the buyer. This is the ID you use in your own system — Vouch does not manage user accounts for you.

string

required

Your platform’s unique identifier for the seller.

number

required

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

array

required

An ordered list of milestones that define how the escrowed funds are released. At least one milestone is required.

Show Milestone object

string

required

A short label for this milestone, e.g. "Sprint 1: Design".

number

required

The amount allocated to this milestone in the smallest currency unit.

string

default:"NGN"

ISO 4217 currency code. Defaults to NGN if omitted.

string

Optional email address for the buyer. Used for notifications and virtual account labelling.

string

Optional display name for the buyer. Appears on the generated virtual account when the agreement is funded.

Examples

curl --request POST \
  --url https://vouch-fmql.onrender.com/v1/escrow/agreements \
  --header "Content-Type: application/json" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "buyerExternalId": "client_buyer_123",
    "sellerExternalId": "client_seller_456",
    "totalAmount": 500000,
    "currency": "NGN",
    "buyerEmail": "finance@acme.com",
    "buyerName": "Acme Holdings",
    "milestones": [
      { "title": "Sprint 1: Design", "amount": 200000 },
      { "title": "Sprint 2: Development", "amount": 300000 }
    ]
  }'

import Vouch from "@vouch/sdk";

const vouch = new Vouch({ apiKey: process.env.VOUCH_API_KEY });

const agreement = await vouch.escrow.create({
  buyerExternalId: "client_buyer_123",
  sellerExternalId: "client_seller_456",
  totalAmount: 500000,
  currency: "NGN",
  buyerEmail: "finance@acme.com",
  buyerName: "Acme Holdings",
  milestones: [
    { title: "Sprint 1: Design", amount: 200000 },
    { title: "Sprint 2: Development", amount: 300000 },
  ],
});

console.log(agreement.id); // "agr_clx8f7k2z000108l4"

Response

A successful request returns HTTP 201 Created with the full agreement object.

string

Vouch’s unique identifier for this agreement, prefixed with agr_.

string

The ID of the developer account that created this agreement.

string

The buyer identifier you provided.

string

The seller identifier you provided.

string

Current lifecycle status of the agreement. Newly created agreements always start as PENDING.

string | null

The virtual bank account number used to fund this agreement. This is null until a successful payment risk assessment is completed with a GREEN or AMBER flag.

number

Total value of the agreement in the smallest currency unit.

string

ISO 4217 currency code for this agreement.

string

ISO 8601 timestamp of when the agreement was created.

array

The milestones associated with this agreement.

Show Milestone fields

string

Unique identifier for the milestone, prefixed with ms_.

string

The label you provided for this milestone.

number

The amount allocated to this milestone in the smallest currency unit.

boolean

Whether the buyer has confirmed completion of this milestone.

boolean

Whether the seller has confirmed completion of this milestone.

string

Current status of this individual milestone. One of PENDING, BUYER_CONFIRMED, SELLER_CONFIRMED, or COMPLETED.

Example Response

{
  "id": "agr_clx8f7k2z000108l4",
  "developerId": "dev_abc123",
  "buyerExternalId": "client_buyer_123",
  "sellerExternalId": "client_seller_456",
  "status": "PENDING",
  "virtualAccountNo": null,
  "totalAmount": 500000,
  "currency": "NGN",
  "createdAt": "2026-07-01T12:00:00.000Z",
  "milestones": [
    {
      "id": "ms_001",
      "title": "Sprint 1: Design",
      "amount": 200000,
      "buyerConfirmed": false,
      "sellerConfirmed": false,
      "status": "PENDING"
    },
    {
      "id": "ms_002",
      "title": "Sprint 2: Development",
      "amount": 300000,
      "buyerConfirmed": false,
      "sellerConfirmed": false,
      "status": "PENDING"
    }
  ]
}

Identity

Fraud

Escrow

Developer

Create an Escrow Agreement — Vouch API

Endpoint

Request

Headers

Body Parameters

Examples

Response

Example Response

​Endpoint

​Request

​Headers

​Body Parameters

​Examples

​Response

​Example Response

Endpoint

Request

Headers

Body Parameters

Examples

Response

Example Response