Release & resolve (disputes) overview

This group covers the end of an escrow: the buyer releasing funds on delivery, either party raising a dispute, and you (the merchant) resolving it. It also includes the merchant-wide read feeds. See Escrow lifecycle for the states involved.

Watch the customer-id header carefully here:

Per-customer routes (confirm, submit dispute, my disputes) require it.
Merchant-wide routes (List all disputes, Escrow feeds, Resolve dispute) must not send it.

Release & dispute (per-customer)

Route	Method & path	What it does
Buyer confirm payment	`POST /v1/escrow/confirm-payment/{escrowId}`	Buyer confirms delivery on a standard escrow; releases the full amount and closes it `COMPLETED`. `customer-id` = buyer.
Submit dispute	`POST /v1/escrow/submit-dispute/{paymentToken}`	Open or reply to a dispute (escrow must be `OPENED`). `multipart/form-data` with a `message` and optional evidence `file`. Only the buyer can open a dispute; the seller can only respond once one is raised. Milestone escrows can’t be disputed. `customer-id` required.
List my disputes	`GET /v1/escrow/dispute/get`	A customer’s disputes, with optional `paymentToken` / date filters. `customer-id` required.
Get dispute by escrow ID	`GET /v1/escrow/dispute/get/{escrowId}`	The dispute thread for one escrow. `customer-id` required.

Merchant-wide (no `customer-id`)

Route	Method & path	What it does
List all customers’ disputes	`GET /v1/escrow/all-dispute`	Every dispute across all your customers, paginated.
Get escrow feeds	`GET /v1/escrow/feeds`	All customers’ escrows, with `status` / `customerId` / `categoryId` / date filters.
Resolve dispute	`POST /v1/escrow/dispute/resolve/{escrowId}`	You settle the dispute. `multipart/form-data`: `resolution` text + `status` (`COMPLETED` releases to seller, `REFUNDED` returns to buyer, `SPLIT` divides between both) + `sellerAmount` and `buyerAmount` on a split + optional `additionalFeeRefundable` (who keeps the delivery fee on a refund or split) + optional `file`.

Resolution paths

Happy path

Buyer confirms → COMPLETED.

Contested

The buyer opens a dispute (DISPUTED); the seller responds (INVESTIGATING). Standard and milestone escrows; vaults cannot be disputed.

Merchant decides

You resolve → COMPLETED (seller paid), REFUNDED (buyer refunded), or SPLIT (held funds divided between the two in amounts you name).

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: Debit Cards

Other: Crypto Whitelist

Other: Misc

Release & resolve (disputes) overview

Release & dispute (per-customer)

Merchant-wide (no `customer-id`)

Resolution paths

​Release & dispute (per-customer)

​Merchant-wide (no customer-id)

​Resolution paths

Release & dispute (per-customer)

Merchant-wide (no `customer-id`)

Resolution paths