Escrow overview

A standard escrow is a single-payment link: the buyer funds it once, and the full amount is released to the seller on confirmation. This group covers creating the link, editing it before it’s funded, and the seller’s claim path. For the full state machine see Escrow lifecycle; for the call-by-call walkthrough see How it works.

customer-id = the seller when creating. Edit, delete and claim are seller-only and act on the escrow’s paymentToken. Buyer-side actions (funding, confirming) live under Payments and Disputes.

Endpoints

Route	Method & path	What it does
Create escrow	`POST /v1/escrow/create`	Generates a standard escrow link. `multipart/form-data` (up to 5 images). Required: `amount` (min 1000, two decimal places), `purpose`, `whoPays`, `maxDelivery` (1 to 365), `deliveryTimeline`. Returns `id` + `paymentToken`; `state: AWAITING_PAYMENT`. `customer-id` = seller. Omit the header only if your business account is the seller itself.
Edit escrow	`PUT /v1/escrow/edit/{paymentToken}`	Replace amount/purpose/delivery/images. Same required fields as creation, even when unchanged. Allowed only while `AWAITING_PAYMENT` and only by the seller. New images are appended.
Update additional fee	`PUT /v1/escrow/additional-fee/{paymentToken}`	Sets your own charge (delivery, handling) on top of the escrow. Merchant super-admin only, no `customer-id`, standard escrows only, and only while `PENDING`. Paid to your merchant wallet on completion as a `delivery` transaction.
Delete escrow	`DELETE /v1/escrow/delete/{paymentToken}`	Removes an unfunded escrow. Allowed only while `AWAITING_PAYMENT`.
Verify payment token	`GET /v1/escrow/verify/{paymentToken}`	Resolves a link to its full escrow details, used by the buyer to preview before paying.
Claim funds	`GET /v1/escrow/claim-funds/{paymentToken}`	Seller releases funds to themselves. Allowed only when `OPENED` and one day has passed after the delivery window. Closes as `CLAIMED`.
List escrow transactions	`GET /v1/escrow/transactions`	Paginated escrows for the caller. `type` (`sales` or `buy`) is required. Optional `status`, `categoryId`, `page`, `limit`.

How a standard escrow flows

Create (seller)

POST /v1/escrow/create → AWAITING_PAYMENT. Editable/deletable until funded.

Price the delivery (merchant, optional)

PUT /v1/escrow/additional-fee/{paymentToken} adds your delivery charge once you know it. Adjustable right up until the buyer pays.

Fund (buyer)

Buyer pays via Pay escrow → OPENED.

Release

Buyer confirms → COMPLETED, or the seller claims after the window → CLAIMED.

Selling more than one unit from a single link (totalQuantity > 1) changes this behaviour: each buyer gets a cloned escrow. Read Multi-quantity escrows.

1. Onboard customers

2. Catalog (optional)

3. Create the deal: Escrow

4. Create the deal: Milestone Escrow

5. Stake & resolve: Vault Escrow

6. Fund it: Payments

7. Release & resolve: Disputes

Other: Merchant Account

Other: Misc

Endpoints

How a standard escrow flows

​Endpoints

​How a standard escrow flows

Endpoints

How a standard escrow flows