Escrow / Standard Escrow
Standard Escrow
Initiate a simple, single-release escrow between a buyer and a seller. The buyer's wallet is debited immediately, and funds are held in the escrow GL until goods are confirmed received or the escrow is cancelled.
Initiate an 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
}
]
}'| Field | Type | Required | Notes |
|---|---|---|---|
| buyerId | UUID string | Yes | The user acting as the buyer. |
| sellerId | UUID string | Yes | The user acting as the seller. |
| buyerAccountId | UUID string | Yes | The buyer's wallet account ID to draw funds from. |
| externalReference | string | Yes | Your internal order or reference ID. |
| items | InvoiceItemDto[] | Yes | List of items. Min 1 item. |
| sellerAccountId | UUID string | No | Optional target account for the seller payout. |
| splitPlan | EscrowSplitPlanDto | No | Overrides default fee split if provided. |
| feePayer | BUYER | SELLER | 50_50 | No | Defaults to SELLER. |
| externalInvoiceNumber | string | No | Optional invoice ID for reference. |
| milestones | CreateMilestoneDto[] | No | Optional stages for partial release. Leave empty for standard escrow. |
Response — 201 Created
{
"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"
}Cancel an Escrow
Escrows can be cancelled if they are in the INITIATED or DISPUTED state. Cancelling refunds the buyer entirely.
curl -X POST "https://api.switchlock.co.zw/v1/escrow/esc_01hx.../cancel" \
-H "x-api-key: YOUR_API_KEY" \
-H "x-company-id: YOUR_COMPANY_ID" \
-H "Content-Type: application/json" \
-d '{
"actor": "BUYER",
"reason": "Seller requested cancellation due to stock issues"
}'| Field | Type | Required | Notes |
|---|---|---|---|
| actor | BUYER | SELLER | SYSTEM | Yes | Who is initiating the cancellation. |
| reason | string | Yes | A descriptive reason for cancellation. Stored in the timeline. |