Overview
SwitchLock escrow holds funds in a neutral account until both parties confirm the deal is done. Neither buyer nor seller can move the money unilaterally once it is locked.
What is Escrow?
Direct payment is a trust problem: the buyer has no guarantee the goods will arrive, and the seller has no guarantee they will get paid. Escrow breaks the deadlock by introducing a neutral hold. The buyer's funds are locked the moment the deal is created. The seller ships knowing payment exists. The buyer confirms receipt before the seller is paid. Neither party can access the funds until the agreed conditions are met.
Lock
Buyer funds move to a system escrow account. The buyer's wallet balance decreases immediately.
Deliver
Seller dispatches goods and submits a delivery note. Buyer reviews and confirms.
Release
On confirmation, funds release to the seller minus applicable fees. The escrow closes.
| Mechanism | Direct Payment | Escrow |
|---|---|---|
| Buyer risk | High — pays before receiving | Low — funds held until confirmed |
| Seller risk | Low — gets paid upfront | Low — funds locked at creation |
| Dispute resolution | Manual / external | Built-in negotiation + admin resolve |
| Partial delivery | Not supported | Milestone-based partial releases |
| Reversal | Requires seller cooperation | Automatic refund on cancel |
Two Roles
Every escrow involves exactly two principals. The same user can be a buyer in one escrow and a seller in another, but they cannot occupy both roles in the same escrow.
- Initiates the escrow and locks funds
- Submits a Goods Received Note (GRN) on delivery
- Can raise a dispute if delivery is unsatisfactory
- Receives a refund if the escrow is cancelled
- Ships goods and submits a Delivery Note
- Receives payout after buyer confirms receipt
- Can propose a negotiation on the split plan
- Cannot cancel once goods have shipped
A buyer and seller must be different users. Attempting to create an escrow where buyerId === sellerId will return a 400 validation error.
State Machine
An escrow moves through a defined set of statuses. Transitions are enforced server-side — you cannot skip states or go backwards except via the dispute and cancel paths.
Primary flow
Dispute path
Cancel path
| Status | Meaning |
|---|---|
| INITIATED | Funds locked from buyer. Awaiting seller dispatch. |
| DELIVERY_NOTE_READY | Seller submitted a delivery note. Awaiting buyer GRN. |
| GOODS_RECEIVED | GRN matched the delivery note. Release is in progress. |
| DISPUTED | GRN mismatch or manual dispute raised. Funds frozen. |
| COMPLETED | All funds distributed. Escrow is closed. |
| CANCELLED | Cancelled before delivery or during dispute. Refund issued. |
Key Operations
All endpoints are under /v1/escrow and require an API key plus the x-company-id header.
| Operation | Endpoint | Caller | Effect |
|---|---|---|---|
| Initiate | POST /v1/escrow/initiate | Buyer | Locks funds; creates escrow record |
| Delivery note | POST /v1/escrow/:id/delivery-note | Seller | Records dispatch; moves to DELIVERY_NOTE_READY |
| Goods received | POST /v1/escrow/:id/goods-received | Buyer | Confirms receipt; triggers auto-release on match |
| Manual release | POST /v1/escrow/:id/release | System/Admin | Releases all or a specific milestone |
| Raise dispute | POST /v1/escrow/:id/dispute | Buyer/Seller | Freezes escrow; initiates negotiation flow |
| Cancel | POST /v1/escrow/:id/cancel | Buyer/Seller/System | Refunds buyer; only from INITIATED or DISPUTED |
The system also runs automated sweeps: escrows left in INITIATED for more than 7 days are auto-cancelled. Escrows in DELIVERY_NOTE_READY for more than 24 hours are auto-released.
Initiate Your First Escrow
Create a new escrow by posting the buyer, seller, and line items. The total is calculated from item prices — you never pass a total amount directly.
curl -X POST "https://api.switchlock.co.zw/v1/escrow/initiate" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-company-id: YOUR_COMPANY_ID" \
-H "Content-Type: application/json" \
-d '{
"buyerId": "usr_buyer_uuid",
"sellerId": "usr_seller_uuid",
"buyerAccountId": "acc_buyer_usd_uuid",
"externalReference": "order-8821",
"feePayer": "SELLER",
"items": [
{
"name": "Industrial Generator 15kVA",
"quantity": 1,
"pricePerUnit": 450000
}
]
}'{
"id": "esc_01hx...",
"status": "INITIATED",
"totalAmount": 450000,
"splitPlan": {
"seller_payout_cents": 441000,
"system_fee_cents": 4500,
"service_fee_cents": 4500
},
"externalReference": "order-8821",
"createdAt": "2026-06-23T09:12:00.000Z"
}