Escrows Overview

The Escrows API allows you to create and manage secure escrow transactions between buyers and sellers.

​

Overview

Escrows are secure transactions where funds are held until both parties agree that the transaction is complete. The API provides endpoints to:

• Create new escrow transactions
• List and filter your escrows
• Get detailed information about specific escrows
• Update, deliver, and cancel pending escrows
• Get contract details and PDF URLs
• Receive real-time notifications via webhooks

For critical actions that require user interaction (signing contracts, paying, completing, disputes, and cancellation flows), use Checkout Sessions to redirect users to dhmad.tn.

​

Escrow Modes

When creating an escrow, set the mode field to choose the transaction flow. All modes share the same statuses (pending → paid → …) but differ in whether a contract is used and how delivery completes.

​

Standard mode

• Set mode: "standard" (default) with contractTerms and estimatedDeliveryDays.
• A contract is automatically created; both parties must sign before the buyer can pay.
• Checkout actions: sign_contract → accept_pay → (seller delivers) → complete.
• Provide sellerEmail when the seller is a third party, or omit it to use your associated user as seller.

State flow: pending → paid → delivered → completed

​

Quick mode

• Set mode: "quick" with estimatedDeliveryDays. Do not send contractTerms or autoSign.
• No contract is created; the response includes contract: null and escrow.mode: "quick".
• Checkout actions: accept_pay → (seller delivers) → complete. The sign_contract action returns 400 (QUICK_ESCROW_NO_CONTRACT).
• Use when escrows are between two other parties (sellerEmail required) and you want a faster checkout without a contract — e.g. product sales, digital downloads with buyer confirmation.
• Minimum internal ledger value (amountTnd) is 5 TND after FX lock (same as standard).

State flow: pending → paid → delivered → completed

​

Quick mode with purchase proof

Add fulfillmentPolicy when you need the seller to prove purchase or shipment before delivery is unlocked — e.g. marketplaces, crowd-shipping, or product-deal apps.

• Set mode: "quick" and fulfillmentPolicy.type: "purchase_proof_required".
• After the buyer pays, escrow status stays paid while proofInfo.phase tracks the proof gate (waiting_seller_proof → review → accepted).
• Checkout actions: accept_pay → submit_proof (seller) → review_proof (buyer) → (seller delivers) → complete.
• Fetch proof files with GET /escrows/:id/proof; handle escrow.proof.* webhooks.

See the Quick Escrow with Proof guide for the full walkthrough.

​

Instant mode

For digital goods (e.g. in-app coins, AI credits), the full standard flow has too many steps and can hurt conversion. Use instant when you are the seller:

• Set mode: "instant" and omit sellerEmail (your associated user is the seller). Do not send contractTerms or autoSign.
• estimatedDeliveryDays is optional (defaults to 1).
• No contract is created; the response includes contract: null and escrow.mode: "instant".
• Checkout action: accept_pay only. The actions sign_contract and complete return 400.
• When you receive the escrow.status.updated webhook (pending → paid), deliver the digital goods (e.g. credit the user’s balance).
• Call Deliver Escrow (POST /api/v1/escrows/:id/deliver). The escrow auto-completes and funds are released immediately (no buyer confirmation step).
• Minimum internal ledger value (amountTnd) is 0.01 TND after FX lock.
• Guest checkout (buyer pays without a DHMAD account) is supported for instant escrows via accept_pay.

State flow: pending → paid → completed (the delivered state is skipped; calling deliver transitions directly to completed)

​

Mode comparison

​

Escrow Statuses

Escrows progress through the following statuses:

​

Buyer Handling

When creating an escrow, you provide the buyer’s email address. The system handles two scenarios:

​

Existing User

If the buyer email corresponds to an existing user account:

• The escrow is linked to their account
• They receive an in-app notification
• They receive an email notification
• They can view and interact with the escrow immediately

​

New User

If the buyer email doesn’t correspond to an existing user:

• An invitation email is sent with a registration link
• The escrow is created with the email stored
• Once they register using the link, the escrow is automatically linked to their account
• The registration link includes a secure token for verification

​

API Endpoints (Direct)

These endpoints can be called directly from your server using your API key:

• Create Escrow - Create a new escrow transaction
• List Escrows - Get a paginated list of escrows
• Get Escrow - Get detailed information about a specific escrow
• Get Escrow Proof - Proof attachments with viewUrl (Quick Escrow with Proof)
• Get Contract - Get contract details and PDF URL (standard mode only)
• Update Escrow - Update a pending escrow
• Deliver Escrow - Seller marks escrow as delivered
• Reject Delivery - Buyer rejects delivery and returns escrow to paid
• Cancel Escrow - Cancel a pending escrow

​

Checkout Sessions (Redirect)

For actions that require user interaction, use Checkout Sessions to redirect users to dhmad.tn:

• Sign Contract — User signs the escrow contract (standard mode only)
• Accept & Pay — Buyer reviews and pays for the escrow (all modes)
• Submit proof — Seller uploads purchase/shipment proof (Quick Escrow with Proof only)
• Review proof — Buyer accepts proof or requests corrections (proof escrows only)
• Complete — Buyer confirms delivery and releases funds (standard and quick modes; not instant)
• Dispute — User opens a dispute
• Request cancellation — Buyer requests cancellation (paid or delivered; buyer email only)
• Cancel escrow — Seller cancels immediately (paid or delivered; seller email only)
• Reject / accept cancellation — Seller responds to a pending buyer cancellation request (seller email)

---