Open an escrow

An escrow agreement holds a buyer’s money until each stage (a “payment gate”) is approved. No timer ever settles anything: money moves only when a person approves it.

1. Check escrow is on for your currency

Escrow is switched on per currency for your tenant during set-up; ask us if a currency you need isn’t on. Escrow also needs someone to resolve disputes: opening an agreement returns 409 if your tenant’s escrow back-office role has no members.

2. Open the agreement

POST /escrow names the payee by mobile number, email address or username, with the amount, an expiry and, optionally, gates. Leave gates out for a single gate covering the full amount. No money moves yet.

3. Fund it

POST /escrow/{reference}/fund takes the buyer’s money into the agreement’s own account. Funding freezes the terms: until then, PUT /escrow/{reference}/gates can amend them, and POST /escrow/{reference}/cancel cancels a draft.

4. Approve each gate

POST /escrow/{reference}/gate/{gateReference}/approve releases that gate’s amount to the payee. reject refuses it.

When there’s a dispute

POST /escrow/{reference}/gate/{gateReference}/dispute raises a case. Your escrow back-office team decides it: release to the payee, or refund the buyer. Case handling is set up for your tenant; ask us how. There are no partial splits on a dispute.

Every state change arrives as a signed webhook: escrow.funded, escrow.gate_passed, escrow.gate_rejected, escrow.disputed, escrow.released, escrow.refunded and escrow.release_failed.