Create Escrow

# 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",
    "contractTerms": "The seller agrees to deliver a fully functional website within 7 days.",
    "autoSign": true
  }'

# Standard mode — service between two parties (third-party seller), buyer pays fees
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": "Logo design package",
    "amount": 500,
    "currency": "TND",
    "buyerEmail": "buyer@example.com",
    "sellerEmail": "seller@example.com",
    "mode": "standard",
    "contractTerms": "Full design delivery and 2 revisions.",
    "developerFeePercentage": 5,
    "feeBearer": "buyer"
  }'

# Quick mode with purchase proof — seller must prove purchase before delivery
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": "iPhone 15 from Dubai",
    "amount": 2500,
    "currency": "TND",
    "buyerEmail": "buyer@example.com",
    "sellerEmail": "seller@example.com",
    "mode": "quick",
    "feeBearer": "seller",
    "fulfillmentPolicy": {
      "type": "purchase_proof_required",
      "proofUploadDeadlineHours": 24,
      "buyerReviewDeadlineHours": 24,
      "allowedProofTypes": ["receipt", "tracking_proof", "product_photo"]
    }
  }'

# Quick mode — product sale, no contract
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": "Premium template pack",
    "amount": 150,
    "currency": "TND",
    "buyerEmail": "buyer@example.com",
    "sellerEmail": "seller@example.com",
    "mode": "quick"
  }'

# Instant mode — you are the seller (in-app purchase)
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": "100 AI credits",
    "amount": 25,
    "currency": "TND",
    "buyerEmail": "buyer@example.com",
    "mode": "instant"
  }'

# Hourly contract — progressive release (presence of the object is the opt-in)
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": "Hourly contract — React developer",
    "amount": 4000,
    "currency": "TND",
    "buyerEmail": "client@example.com",
    "sellerEmail": "freelancer@example.com",
    "mode": "quick",
    "progressiveRelease": { "autoApproveHours": 48 }
  }'

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

Create a new escrow. Requires API key authentication. The platform fee (DHMAD’s percentage) is applied automatically. Who pays platform and developer fees is controlled by feeBearer (default "seller"). Choose the escrow mode based on your use case — see Escrow Modes for a full comparison:

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

For hourly or recurring work, add progressiveRelease to standard or quick mode so one funded escrow pays out per billing period — see Progressive Release. Developer fee is only for when the seller is a third party (not your associated account); you can set a developer fee percentage so that a portion of the transaction is credited to your associated user account when the escrow completes.

Fee bearer (`feeBearer`)

Platform fees (and any developer fee) can be paid by either party:

Value	Buyer funds (`buyerFundingTnd`)	Seller receives on release
`seller` (default)	Deal amount (`amountTnd`)	Deal amount minus platform + developer fees
`buyer`	Deal amount + platform + developer fees	Full deal amount

Use buyerFundingTnd (returned on create/get) when sizing wallet locks, checkout amounts, and KYC thresholds — not amountTnd alone when feeBearer is buyer. Cancel / full refunds return the buyer’s full funding, including fees when the buyer bore them.

# 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",
    "contractTerms": "The seller agrees to deliver a fully functional website within 7 days.",
    "autoSign": true
  }'

# Standard mode — service between two parties (third-party seller), buyer pays fees
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": "Logo design package",
    "amount": 500,
    "currency": "TND",
    "buyerEmail": "buyer@example.com",
    "sellerEmail": "seller@example.com",
    "mode": "standard",
    "contractTerms": "Full design delivery and 2 revisions.",
    "developerFeePercentage": 5,
    "feeBearer": "buyer"
  }'

# Quick mode with purchase proof — seller must prove purchase before delivery
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": "iPhone 15 from Dubai",
    "amount": 2500,
    "currency": "TND",
    "buyerEmail": "buyer@example.com",
    "sellerEmail": "seller@example.com",
    "mode": "quick",
    "feeBearer": "seller",
    "fulfillmentPolicy": {
      "type": "purchase_proof_required",
      "proofUploadDeadlineHours": 24,
      "buyerReviewDeadlineHours": 24,
      "allowedProofTypes": ["receipt", "tracking_proof", "product_photo"]
    }
  }'

# Quick mode — product sale, no contract
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": "Premium template pack",
    "amount": 150,
    "currency": "TND",
    "buyerEmail": "buyer@example.com",
    "sellerEmail": "seller@example.com",
    "mode": "quick"
  }'

# Instant mode — you are the seller (in-app purchase)
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": "100 AI credits",
    "amount": 25,
    "currency": "TND",
    "buyerEmail": "buyer@example.com",
    "mode": "instant"
  }'

# Hourly contract — progressive release (presence of the object is the opt-in)
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": "Hourly contract — React developer",
    "amount": 4000,
    "currency": "TND",
    "buyerEmail": "client@example.com",
    "sellerEmail": "freelancer@example.com",
    "mode": "quick",
    "progressiveRelease": { "autoApproveHours": 48 }
  }'

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

For quick and instant modes, contract is null.

Request Body

string

required

Title of the escrow (1–200 characters).

number

required

Commercial face amount in currency. After FX lock, standard and quick modes require internal ledger value (amountTnd) of at least 5 TND; instant mode requires at least 0.01 TND.

string

Face currency: "TND" (default), "USD", or "EUR". Ledger, fees, and payouts use amountTnd (TND) locked at creation.

string

required

Email of the buyer. They will be invited to register if they do not have an account.

string

Email of the seller. If omitted, your developer account’s associated user account is used as the seller (required for instant mode). If provided, the seller is that user or an invite. Use standard or quick mode for escrows between two other parties.

string

"standard" (default), "quick", or "instant". See Escrow Modes.

standard — requires contractTerms; creates a contract.
quick — do not send contractTerms or autoSign.
instant — only when you are the seller (omit sellerEmail); do not send contractTerms or autoSign.

string

Who pays the platform service fee (and TVA) and the developer fee. "seller" (default) or "buyer". When "seller", fees are withheld from the seller at release and the buyer funds the deal amount only. When "buyer", fees are added to the buyer’s funding amount and the seller receives the full deal amount.

number

Legacy optional delivery estimate (minimum 1 if provided). Not used by platform enforcement; omit for new integrations. Timing is driven by fulfillment deadlines, completion deadlines, and contractTerms prose instead.

string

Required when mode is "standard". Contract text (max 10,000 characters). Not allowed for "quick" or "instant".

boolean

Default false. If true, the contract is automatically signed by the seller using the signature configured in the developer dashboard. Requires a signature to be set up first. Auto-sign is only available when you are the seller (omit sellerEmail so your associated user account is used). Do not combine autoSign: true with sellerEmail. Not applicable for "quick" or "instant" modes.

number

Optional percentage (0–25) of the escrow amount, credited to your developer account’s associated user when the escrow completes. Only allowed when the seller is a third party (not your associated user account). Not allowed when the seller is your associated account (whether you omit sellerEmail or pass that same email); if violated, the API returns 400. Default is 0. When feeBearer is "seller" (default), this amount is deducted from the seller’s payout (in addition to the platform fee). When feeBearer is "buyer", it is included in the buyer’s funding instead. If you set a value greater than 0, your developer account must be associated with a user account in the developer dashboard; otherwise the request returns 403 Forbidden.

object

Quick Escrow with Proof — only allowed when mode is "quick". Requires the seller to upload purchase/shipment proof after the buyer pays; the buyer reviews on DHMAD before delivery is unlocked. See the Quick Escrow with Proof guide.

type (required when set) — must be "purchase_proof_required".
proofUploadDeadlineHours — hours for seller upload after funding (must be within platform bounds, default 6–72h; returns 400 if out of range; default 24h when omitted).
buyerReviewDeadlineHours — hours for buyer review (same bounds; auto-accept if buyer does nothing).
allowedProofTypes — optional UI hints: receipt, order_confirmation, product_photo, tracking_proof, other. Informational only; DHMAD does not enforce uploads against this list.

object

Hourly / recurring contracts — allowed for standard and quick modes (returns 400 for instant). Lets one funded escrow pay out in slices, one per billing period. See the Progressive Release guide.Presence of this object is the opt-in. Do not send enabled (or any other unknown key) — the schema is strict and those requests return 400.

autoApproveHours — how long the client has to review each payout request before it releases automatically. Must be within platform bounds (default 12–336h; returns 400 if out of range). Defaults to 48h when omitted.
minReleaseTnd — smallest payout slice in TND. Clamped to at least the platform minimum (5 TND).

The client must explicitly accept automatic release when funding the escrow; otherwise payout requests are refused with CONSENT_REQUIRED.

Progressive release (hourly contracts)

When progressiveRelease is set:

Buyer pays via accept_pay and accepts automatic release.
Your backend claims each period with POST /escrows/:id/release-requests — permitted on the seller’s behalf, so the freelancer takes no weekly action.
The client approves (approve_release), rejects (reject_release, which disputes that period only), or lets it auto-release at the deadline.
Top up the same escrow with add_funds when the balance runs low; a zero balance keeps the escrow open.
End the contract with POST /escrows/:id/close, which settles owed periods and refunds the remainder.

Escrow status remains paid across every partial payout; track progress with availableForReleaseTnd, reservedTnd, and the escrow.release_request.* webhooks.

Quick Escrow with Proof

When fulfillmentPolicy.type is purchase_proof_required:

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

Escrow status remains paid during the proof gate; use proofInfo.phase and proof webhooks for progress.

Response Fields (escrow object)

Checkout page and fees

When you redirect users to a Checkout Session, the DHMAD checkout page shows the platform service fee and, if you set developerFeePercentage when creating the escrow, the application / app fee (with your app name when configured). Which party pays those fees follows feeBearer. Use buyerFundingTnd for the amount the buyer actually pays.

Errors

400 Bad Request – Instant mode with third-party seller

When mode is "instant" and sellerEmail is provided:

{
  "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)."
}

Use standard or quick mode and provide sellerEmail for escrows between two other parties.

400 Bad Request – Contract terms on quick/instant mode

When mode is "quick" or "instant" and contractTerms is provided:

{
  "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

When developerFeePercentage is greater than 0 and the seller (resolved from the request) is your developer account’s associated user:

{
  "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)."
}

Omit developerFeePercentage or set it to 0 when you are the seller (or when the seller email is your associated account).

400 Bad Request – Auto-sign not allowed

When autoSign is true but the seller is not your associated user account (for example, you provided sellerEmail for a third party, or the seller has not registered yet):

{
  "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."
}

Other auto-sign failures return 400 with messages such as:

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

When you are the seller, omit sellerEmail, set up your signature in the Developer Dashboard, and ensure your developer account is associated with your DHMAD user account.

403 Forbidden – Developer fee without associated user

If you send developerFeePercentage greater than 0 and your developer account has no associated user account:

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

Associate your developer account with a user account in the Developer Dashboard to collect developer fees.

403 Forbidden – No seller and no associated user

If you omit sellerEmail and your developer account has 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."
}

Get Started

API Reference

Guides

Developer Portal

Fee bearer (`feeBearer`)

Request Body

Progressive release (hourly contracts)

Quick Escrow with Proof

Response Fields (escrow object)

Checkout page and fees

Errors

400 Bad Request – Instant mode with third-party seller

400 Bad Request – Contract terms on quick/instant mode

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

400 Bad Request – Auto-sign not allowed

403 Forbidden – Developer fee without associated user

403 Forbidden – No seller and no associated user

​Fee bearer (feeBearer)

​Request Body

​Progressive release (hourly contracts)

​Quick Escrow with Proof

​Response Fields (escrow object)

​Checkout page and fees

​Errors

​400 Bad Request – Instant mode with third-party seller

​400 Bad Request – Contract terms on quick/instant mode

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

​400 Bad Request – Auto-sign not allowed

​403 Forbidden – Developer fee without associated user

​403 Forbidden – No seller and no associated user

Fee bearer (`feeBearer`)

Request Body

Progressive release (hourly contracts)

Quick Escrow with Proof

Response Fields (escrow object)

Checkout page and fees

Errors

400 Bad Request – Instant mode with third-party seller

400 Bad Request – Contract terms on quick/instant mode

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

400 Bad Request – Auto-sign not allowed

403 Forbidden – Developer fee without associated user

403 Forbidden – No seller and no associated user