Create Checkout Session

Create a checkout session for a critical escrow action. The session allows you to redirect a specific user to dhmad.tn to perform the action (e.g., sign contract, accept & pay, complete, dispute, handle cancellation, add funds, or refund funds). The user is redirected back to your redirectUrl after completing or abandoning the flow. The API validates that the action is still needed before creating a session. If the action is already done (e.g. the target user has already signed the contract, or payment is already completed), the request returns 400 with a structured error (error.code, error.user_message). Use these to show a clear message in your app instead of redirecting to checkout.

Configure allowed redirect URLs in your Developer Dashboard settings before creating checkout sessions. If no redirect URLs are configured, or if the redirectUrl does not match any allowed URL, the request will fail with a 400 error.

curl -X POST https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/sessions \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "sign_contract",
    "targetUserEmail": "buyer@example.com",
    "redirectUrl": "https://myapp.com/checkout/callback",
    "metadata": {
      "order_id": "ord_123"
    }
  }'

const response = await fetch('https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/sessions', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    action: 'sign_contract',
    targetUserEmail: 'buyer@example.com',
    redirectUrl: 'https://myapp.com/checkout/callback',
    metadata: { order_id: 'ord_123' }
  })
});

const data = await response.json();

import requests

response = requests.post(
    'https://dhmad.tn/api/v1/escrows/507f1f77bcf86cd799439011/sessions',
    headers={
        'Authorization': 'Bearer sk_live_your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'action': 'sign_contract',
        'targetUserEmail': 'buyer@example.com',
        'redirectUrl': 'https://myapp.com/checkout/callback',
        'metadata': {'order_id': 'ord_123'}
    }
)

data = response.json()

{
  "sessionId": "550e8400-e29b-41d4-a716-446655440000",
  "url": "https://dhmad.tn/checkout/550e8400-e29b-41d4-a716-446655440000",
  "expiresAt": "2024-01-15T10:30:00Z"
}

Path Parameters

string

required

Escrow ID

Request Body

string

required

The action the user will perform. Must be one of: sign_contract, accept_pay, complete, dispute, request_cancellation, reject_cancellation, accept_cancellation, cancel_escrow, submit_proof, review_proof, add_funds, refund_funds, approve_release, reject_release. If the action is already done (e.g. contract already signed, payment already made), the API returns 400 with a business rule error—see Error Responses below.Cancellation actions (paid or delivered escrows):

request_cancellation — Buyer only. Target the buyer’s email. The buyer cannot cancel unilaterally after payment; they request cancellation and the seller must accept or reject.
cancel_escrow — Seller only. Target the seller’s email. Cancels immediately and refunds the buyer when applicable.
reject_cancellation / accept_cancellation — Target the seller’s email (counterparty of the buyer who requested). Create these only after a pending cancellation request exists.
Targeting the wrong party returns 400 (CANCELLATION_REQUEST_BUYER_ONLY, CANCEL_ESCROW_SELLER_ONLY, or CHECKOUT_TARGET_NOT_BUYER / CHECKOUT_TARGET_NOT_SELLER).

Funds adjustment actions (paid or delivered escrows):

add_funds — Buyer only. Target the buyer’s email. The buyer adds more money from their DHMAD wallet into the escrow. Fees apply to the added amount only. Requires action step-up on checkout. Not supported for escrows paid via guest checkout.
refund_funds — Seller only. Target the seller’s email. The seller refunds part or all of the remaining ledger balance to the buyer’s wallet. Refunding the full remaining balance cancels the escrow. Requires action step-up on checkout. Not supported for guest-checkout escrows.
Targeting the wrong party returns 400 (CHECKOUT_TARGET_NOT_BUYER / CHECKOUT_TARGET_NOT_SELLER).

Progressive release actions (hourly contracts, paid escrows):

approve_release — Client only. Target the buyer’s email and pass the payout request in metadata.requestId. Releases that period to the seller immediately. Requires action step-up on checkout.
reject_release — Client only. Same targeting and metadata.requestId. Opens a dispute scoped to that period; the amount stays reserved and later periods keep running. No step-up (no money moves).
Both require a progressive-release escrow (created with a progressiveRelease object) and a pending payout request. The seller never acts on these — payout requests are created by your backend, optionally on the seller’s behalf.

By escrow mode:

standard — all actions apply when status allows (except proof actions). complete works from paid or delivered; seller deliver is optional. add_funds / refund_funds apply when paid or delivered.
quick — no contract; sign_contract returns 400 (QUICK_ESCROW_NO_CONTRACT). Typical flow: accept_pay, then buyer complete. Seller may call Deliver Escrow first, but the buyer can complete directly from paid without deliver. With Quick Escrow with Proof, use submit_proof (seller) and review_proof (buyer) while proofInfo.phase requires them; early release from paid is blocked until proof is accepted. add_funds / refund_funds apply when paid or delivered.
instant — only accept_pay (and dispute/cancellation actions) are valid; sign_contract, complete, proof actions, and funds adjustments return 400.

complete action: Buyer releases funds. Valid when escrow status is paid or delivered. Does not require the seller to call deliver first — the buyer can release early from paid if they are satisfied. Returns 409 (PROOF_NOT_ACCEPTED) for Quick Escrow with Proof when proof is not yet accepted.

string

required

Email of the user who will perform the action. Only this user can complete the session.

string

required

URL to redirect the user after they complete or abandon the flow. Must match one of your allowed redirect URLs configured in the developer dashboard. Must use HTTPS (except http://localhost for development).

object

Optional key-value pairs (strings only). Useful for tracking orders or internal references. Values must be 500 characters or less.

Response Fields

No KYC check is performed when creating a checkout session. You can create an accept_pay session regardless of the buyer’s KYC status. If the buyer does not have approved KYC, they will be prompted to complete identity verification inside the DHMAD checkout flow (inline Verify KYC) before they can complete Accept & Pay. You do not receive a separate error code for KYC at session creation time.

Error Responses

When a request is rejected because of a business rule (e.g. the action is already done, or redirect URL is invalid), the API returns 400 Bad Request with an error object. Use error.code to branch in your app and error.user_message to show a clear message to the end user; error.message is for developers and logging. The table below lists all error codes returned by this endpoint. Business rule error shape (400)

{
  "error": {
    "code": "CONTRACT_ALREADY_SIGNED",
    "type": "business_rule_violation",
    "message": "Cannot create checkout session: this signer has already signed the contract.",
    "user_message": "This contract has already been signed."
  }
}

Code	When
`NO_REDIRECT_URLS_CONFIGURED`	Developer has no allowed redirect URLs in dashboard settings.
`REDIRECT_URL_NOT_ALLOWED`	`redirectUrl` does not match any allowed redirect URL.
`REDIRECT_URL_MUST_BE_HTTPS`	`redirectUrl` is not HTTPS (except `http://localhost`).
`INSTANT_ESCROW_NO_CONTRACT`	Action is `sign_contract` but escrow is instant (no contract). Use `accept_pay` instead.
`INSTANT_ESCROW_NO_COMPLETE_STEP`	Action is `complete` but escrow is instant; completion happens via deliver endpoint.
`QUICK_ESCROW_NO_CONTRACT`	Action is `sign_contract` but escrow is quick (no contract). Use `accept_pay` instead.
`CONTRACT_ALREADY_SIGNED`	Action is `sign_contract` and the target user has already signed the contract.
`PAYMENT_ALREADY_DONE`	Action is `accept_pay` but the escrow is already paid, delivered, or completed.
`ESCROW_ALREADY_COMPLETED`	Action is `complete` but the escrow is already completed.
`DISPUTE_ALREADY_OPENED`	Action is `dispute` but a dispute has already been opened.
`CANCELLATION_REQUEST_INVALID_STATUS`	Action is `request_cancellation` but escrow is not `paid` or `delivered`.
`CANCELLATION_REQUEST_BUYER_ONLY`	Action is `request_cancellation` but `targetUserEmail` is the seller. Use `cancel_escrow` instead.
`CANCEL_ESCROW_INVALID_STATUS`	Action is `cancel_escrow` but escrow is not `paid` or `delivered`.
`CANCEL_ESCROW_SELLER_ONLY`	Action is `cancel_escrow` but `targetUserEmail` is the buyer. Use `request_cancellation` instead.
`CHECKOUT_TARGET_NOT_BUYER`	Action is `request_cancellation`, `add_funds`, or another buyer-only action but `targetUserEmail` is not the buyer.
`CHECKOUT_TARGET_NOT_SELLER`	Action is `cancel_escrow`, `refund_funds`, or another seller-only action but `targetUserEmail` is not the seller.
`CANCELLATION_ALREADY_REQUESTED`	Action is `request_cancellation` but a cancellation has already been requested or processed.
`NO_PENDING_CANCELLATION`	Action is `reject_cancellation` or `accept_cancellation` but there is no pending cancellation request.
`FUNDS_ADJUSTMENT_INVALID_STATUS`	Action is `add_funds` or `refund_funds` but escrow is not `paid` or `delivered`.
`GUEST_ESCROW_ADJUSTMENTS_NOT_SUPPORTED`	Action is `add_funds` or `refund_funds` but the escrow was paid via guest checkout.
`BUYER_NOT_LINKED`	Action is a funds adjustment but the buyer account is not linked yet.
`DISPUTE_OPEN`	Action is `add_funds` or `refund_funds` but a dispute is open.
`CANCELLATION_PENDING`	Action is `add_funds` or `refund_funds` but a cancellation request is pending.
`PROGRESSIVE_RELEASE_NOT_ENABLED`	Action is `approve_release` or `reject_release` but the escrow does not use progressive release.
`RELEASE_REVIEW_INVALID_STATUS`	Action is `approve_release` or `reject_release` but the escrow is not `paid`.
`RELEASE_REQUEST_ID_REQUIRED`	Action is `approve_release` or `reject_release` but `metadata.requestId` is missing.
`RELEASE_REQUEST_NOT_FOUND`	No payout request with that `requestId` exists on the escrow.
`RELEASE_REQUEST_NOT_PENDING`	The named payout request has already been decided.

Example: contract already signed

{
  "error": {
    "code": "CONTRACT_ALREADY_SIGNED",
    "type": "business_rule_violation",
    "message": "Cannot create checkout session: this signer has already signed the contract.",
    "user_message": "This contract has already been signed."
  }
}

Example: payment already done

{
  "error": {
    "code": "PAYMENT_ALREADY_DONE",
    "type": "business_rule_violation",
    "message": "Cannot create checkout session: payment has already been made for this escrow.",
    "user_message": "Payment has already been completed for this transaction."
  }
}

Handle these in your app by checking response.error?.code and displaying response.error?.user_message to the user instead of redirecting to checkout.

401 Unauthorized

{
  "error": "Unauthorized"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "You do not have access to this escrow."
}

404 Not Found

Escrow Not Found

{
  "error": "Escrow not found"
}

Developer Not Found

{
  "error": "Developer not found"
}

Sessions expire 30 minutes after creation. Ensure users complete the flow within this window, or create a new session if needed.

For escrows created with mode: "instant", only the accept_pay action (and dispute/cancellation actions) is valid. Do not use sign_contract or complete; they will return 400. After the buyer pays, deliver the digital goods and call Deliver Escrow to auto-complete and release funds.

Get Started

API Reference

Guides

Developer Portal

Path Parameters

Request Body

Response Fields

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

​Path Parameters

​Request Body

​Response Fields

​Error Responses

​401 Unauthorized

​403 Forbidden

​404 Not Found

Path Parameters

Request Body

Response Fields

Error Responses

401 Unauthorized

403 Forbidden

404 Not Found