> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dhmad.tn/llms.txt
> Use this file to discover all available pages before exploring further.

# Escrows Overview

> Introduction to the Escrows API

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](/api-reference/checkout-sessions/overview)** to redirect users to dhmad.tn.

<Warning>
  Your developer account must be associated with a user account to create escrows (unless you provide a `sellerEmail`). The associated user account must have email verification completed. Phone verification is only required when the buyer accepts and pays, not at escrow creation.
</Warning>

## 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.

<CardGroup cols={3}>
  <Card title="standard" icon="file-signature">
    Full flow with a contract both parties sign before payment. Best for services and freelance work between two users.
  </Card>

  <Card title="quick" icon="bolt">
    No contract; buyer pays immediately, seller delivers, buyer confirms to release funds. Best for physical or digital products between two users.
  </Card>

  <Card title="instant" icon="zap">
    No contract; you are the seller (omit `sellerEmail`). Buyer pays in one step; calling deliver auto-completes and releases funds. Best for in-app purchases and digital goods.
  </Card>
</CardGroup>

### 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](/api-reference/escrows/get-escrow-proof)**; handle **`escrow.proof.*`** webhooks.

See the **[Quick Escrow with Proof guide](/guides/quick-escrow-with-proof)** 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](/api-reference/escrows/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

|                                           | **standard**                    | **quick**                   | **instant**                   |
| ----------------------------------------- | ------------------------------- | --------------------------- | ----------------------------- |
| Contract                                  | Yes                             | No                          | No                            |
| Seller                                    | Any user (`sellerEmail` or you) | Third party (`sellerEmail`) | You only (omit `sellerEmail`) |
| Buyer confirms after delivery             | Yes                             | Yes                         | No (auto-complete on deliver) |
| `contractTerms`                           | Required                        | Not allowed                 | Not allowed                   |
| `estimatedDeliveryDays`                   | Required                        | Required                    | Optional (default 1)          |
| Min `amountTnd`                           | 5 TND                           | 5 TND                       | 0.01 TND                      |
| Checkout: `sign_contract`                 | Yes                             | No (400)                    | No (400)                      |
| Checkout: `accept_pay`                    | Yes                             | Yes                         | Yes                           |
| Checkout: `complete`                      | Yes                             | Yes                         | No (400)                      |
| `fulfillmentPolicy` (proof gate)          | No                              | Optional                    | No                            |
| Checkout: `submit_proof` / `review_proof` | No                              | When proof enabled          | No                            |

## Escrow Statuses

Escrows progress through the following statuses:

<CardGroup cols={2}>
  <Card title="pending" icon="clock">
    Escrow created, waiting for payment. The buyer needs to accept and pay.
  </Card>

  <Card title="paid" icon="check">
    Payment received and locked in escrow. Waiting for seller to deliver.
  </Card>

  <Card title="delivered" icon="truck">
    Service/product delivered. Waiting for buyer to confirm completion. Skipped in instant mode.
  </Card>

  <Card title="completed" icon="circle-check">
    Transaction completed successfully. Funds released to seller.
  </Card>

  <Card title="cancelled" icon="x">
    Escrow was cancelled. Funds returned to buyer if payment was made.
  </Card>
</CardGroup>

## 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](/api-reference/escrows/create-escrow)** - Create a new escrow transaction
* **[List Escrows](/api-reference/escrows/list-escrows)** - Get a paginated list of escrows
* **[Get Escrow](/api-reference/escrows/get-escrow)** - Get detailed information about a specific escrow
* **[Get Escrow Proof](/api-reference/escrows/get-escrow-proof)** - Proof attachments with `viewUrl` (Quick Escrow with Proof)
* **[Get Contract](/api-reference/escrows/get-contract)** - Get contract details and PDF URL (standard mode only)
* **[Update Escrow](/api-reference/escrows/update-escrow)** - Update a pending escrow
* **[Deliver Escrow](/api-reference/escrows/deliver-escrow)** - Seller marks escrow as delivered
* **[Reject Delivery](/api-reference/escrows/reject-delivery-escrow)** - Buyer rejects delivery and returns escrow to paid
* **[Cancel Escrow](/api-reference/escrows/cancel-escrow)** - Cancel a pending escrow

## Checkout Sessions (Redirect)

For actions that require user interaction, use [Checkout Sessions](/api-reference/checkout-sessions/overview) 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](/guides/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)

***

<Info>
  Escrow amounts support face currencies **TND**, **USD**, and **EUR** via the `currency` field. The platform ledger uses TND only: `amountTnd` is locked at creation and used for fees and payouts. See [Create Escrow](/api-reference/escrows/create-escrow) for details.
</Info>