Create Escrow

• standard (default) — contract + sign + pay + deliver + complete. Use with sellerEmail for escrows between two parties.
• quick — no contract; pay → deliver → buyer confirms. Use with sellerEmail for product sales without a contract. Optionally add fulfillmentPolicy for Quick Escrow with Proof (seller uploads proof before delivery).
• instant — no contract; you are the seller (omit sellerEmail); pay → deliver auto-completes. Use for in-app digital goods.

# Standard mode — you are the seller with auto-sign (omit sellerEmail)
curl -X POST https://dhmad.tn/api/v1/escrows \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Web Development Service",
    "amount": 1000,
    "currency": "TND",
    "buyerEmail": "buyer@example.com",
    "mode": "standard",
    "estimatedDeliveryDays": 7,
    "contractTerms": "The seller agrees to deliver a fully functional website within 7 days.",
    "autoSign": true
  }'

{
  "message": "Escrow created successfully",
  "escrow": {
    "id": "507f1f77bcf86cd799439011",
    "title": "Website design",
    "amount": 500,
    "currency": "TND",
    "amountTnd": 500,
    "escrowFee": 25,
    "developerFee": 25,
    "developerFeePercentage": 5,
    "status": "pending",
    "mode": "standard",
    "seller": null,
    "sellerEmail": "seller@example.com",
    "buyer": null,
    "buyerEmail": "buyer@example.com",
    "estimatedDeliveryDays": 14,
    "createdAt": "2024-01-15T10:00:00.000Z"
  },
  "contract": {
    "id": "507f1f77bcf86cd799439012",
    "pdfUrl": null,
    "sellerSigned": false,
    "buyerSigned": false,
    "isFullySigned": false
  }
}

​

Request Body

​

Quick Escrow with Proof

1. Buyer pays via accept_pay checkout session.
2. Seller uploads proof via submit_proof checkout session.
3. Buyer reviews via review_proof checkout session (or proof auto-accepts after deadline).
4. Seller delivers only after proof is accepted (proofInfo.phase is accepted or accepted_by_timeout).
5. Fetch proof files with GET /escrows/:id/proof; subscribe to escrow.proof.* webhooks.

​

Response Fields (escrow object)

​

Checkout page and fees

​

Errors

​

400 Bad Request – Instant mode with third-party seller

{
  "error": "Bad Request",
  "message": "Instant mode is only available when you are the seller (omit sellerEmail). For escrows between two other parties, use mode: standard (with a contract) or mode: quick (no contract)."
}

​

400 Bad Request – Contract terms on quick/instant mode

{
  "error": "Bad Request",
  "message": "Contract terms are not applicable for quick mode (no contract is created). Use mode: standard to include a contract."
}

​

400 Bad Request – Developer fee when seller is your associated account

{
  "error": "Bad Request",
  "message": "Developer fee is not allowed when the seller is your associated user account. Use developerFeePercentage only when the seller is a third party (different from your associated account)."
}

​

400 Bad Request – Auto-sign not allowed

{
  "error": "Bad Request",
  "message": "Auto-sign is only available when you are the seller (omit sellerEmail). When specifying a sellerEmail, the seller must sign the contract themselves."
}

• No signature configured in the developer dashboard.
• Developer account not associated with a user account (when sellerEmail was provided for a third party).
• sellerEmail refers to a user who has not registered yet (seller must sign after registering).

​

403 Forbidden – Developer fee without associated user

{
  "error": "Forbidden",
  "message": "Developer account must be associated with a user account to collect developer fees. Please associate your account in the developer dashboard."
}

​

403 Forbidden – No seller and no associated user

{
  "error": "Forbidden",
  "message": "Developer account must be associated with a user account to create escrows. Please associate your account in the developer dashboard."
}