Create Payout Request

Claim a slice of a funded progressive-release escrow — one request per billing period, such as a weekly timesheet on an hourly contract. The escrow must have been created with a progressiveRelease object. You can call this on the seller’s behalf when your application created the escrow, so the freelancer takes no weekly action. The amount is reserved against the escrow balance immediately, the client is notified, and the request releases automatically once approvalDeadline passes unless the client decides first. What the client can do:

Approve — the period is released to the seller’s DHMAD balance right away (approve_release checkout session).
Reject — a dispute is opened for that period only. The amount stays reserved and protected while DHMAD reviews it; later periods keep running normally (reject_release checkout session).
Nothing — the request auto-approves and releases at the deadline.

requestId is your idempotency key. Repeating a request with the same requestId returns the existing one with 200 instead of reserving twice, so an at-least-once weekly job is safe to retry.

curl -X POST https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/release-requests \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "timesheet-2026-W12",
    "amount": 24.00,
    "currency": "USD",
    "reference": "Week 12 (Mar 16-22)"
  }'

const response = await fetch(
  'https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/release-requests',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      requestId: 'timesheet-2026-W12',
      amount: 24.0,
      currency: 'USD',
      reference: 'Week 12 (Mar 16-22)'
    })
  }
);

const data = await response.json();

{
  "message": "Payout request created",
  "idempotentReplay": false,
  "releaseRequest": {
    "requestId": "timesheet-2026-W12",
    "amountTnd": 67.61,
    "amountFace": 24,
    "currency": "USD",
    "approvalDeadline": "2026-03-25T09:00:00Z",
    "status": "pending"
  },
  "availableForRelease": 296,
  "reserved": 24,
  "releasedTotal": 0,
  "availableForReleaseTnd": 833.84,
  "reservedTnd": 67.61,
  "releasedTotalTnd": 0,
  "fundedAmount": 320,
  "fundedAmountTnd": 901.45,
  "remainingAmount": 320,
  "remainingAmountTnd": 901.45,
  "refundedTotal": 0,
  "refundedTotalTnd": 0,
  "escrowStatus": "paid"
}

Path Parameters

string

required

Escrow ID

Body Parameters

string

required

Your own identifier for this period, unique per escrow. Doubles as the idempotency key. Letters, numbers and . _ : - only (max 120 characters).

number

The slice in ledger TND. Provide this or face amount. Required unless amount is provided.

number

The slice in the escrow’s face currency (e.g. 24.00 USD). DHMAD converts with the escrow’s locked FX — partners need not invent TND. Ignored when amountTnd is present.

string

TND, USD or EUR. Must match the escrow currency when sending face amount. Defaults to the escrow’s currency.

string

Your own period label, shown to both parties and printed on the fiscal invoice for this release (max 200 characters).

string

Optional internal note (max 500 characters).

Response Fields

Error Responses

400 Bad Request

Progressive release not enabled

{
  "error": "Bad Request",
  "code": "PROGRESSIVE_RELEASE_NOT_ENABLED",
  "message": "Progressive release is not enabled for this escrow."
}

Seller identity not verified

{
  "error": "Bad Request",
  "code": "SELLER_IDENTITY_REQUIRED",
  "message": "The seller must complete identity verification before payouts can be requested."
}

Amount below the minimum slice

{
  "error": "Bad Request",
  "code": "AMOUNT_TOO_SMALL",
  "message": "Release amount must be at least 5 TND."
}

409 Conflict

Insufficient unreserved balance

{
  "error": "Bad Request",
  "code": "INSUFFICIENT_AVAILABLE_BALANCE",
  "message": "Insufficient unreserved balance for this payout request (available 120.5 TND).",
  "availableForReleaseTnd": 120.5,
  "reservedTnd": 3879.5
}

Client has not accepted automatic release

{
  "error": "Bad Request",
  "code": "CONSENT_REQUIRED",
  "message": "The client has not accepted automatic release for this contract."
}

401 Unauthorized

{
  "error": "Unauthorized"
}

404 Not Found

{
  "error": "Escrow not found"
}

Because the seller identity check runs at creation rather than at payout, requests never pile up unpayable. The check is idempotent, so once the freelancer is verified and linked it passes for every future period — there is no weekly friction.

When the balance runs out the escrow stays open and DHMAD emits escrow.balance.exhausted. Pause tracking and prompt the client to top up with an add_funds checkout session; do not close the contract.

Get Started

API Reference

Guides

Developer Portal

Path Parameters

Body Parameters

Response Fields

Error Responses

400 Bad Request

409 Conflict

401 Unauthorized

404 Not Found

​Path Parameters

​Body Parameters

​Response Fields

​Error Responses

​400 Bad Request

​409 Conflict

​401 Unauthorized

​404 Not Found

Path Parameters

Body Parameters

Response Fields

Error Responses

400 Bad Request

409 Conflict

401 Unauthorized

404 Not Found