Skip to main content
Checkout Sessions provide a Stripe Checkout-style redirect flow for critical escrow actions that require user interaction on dhmad.tn. Instead of implementing complex flows in your application, you create a session via the API, redirect the user to dhmad.tn, and they perform the action in a secure, hosted environment.

​
What Are Checkout Sessions?

Checkout Sessions are short-lived, single-use sessions that direct a specific user to dhmad.tn to perform a critical escrow action. The user is authenticated on DHMAD, completes the action (e.g., signing a contract, accepting payment, completing delivery), and is then redirected back to your application with the result. Which checkout actions apply depends on the escrow mode — see Escrow Modes. In standard mode, buyers may need to sign a contract before paying; in quick mode there is no contract and the buyer releases funds with complete (seller deliver is optional); in instant mode only accept_pay is used and completion happens when you call the deliver endpoint. Charges are different: POST /api/v1/charges already returns the checkout URL. That link has no targetUserEmail, lasts 60 minutes, and can be paid by anyone who opens it. Do not create a separate accept_pay session for a charge.

​
When to Use Checkout Sessions

Use Checkout Sessions when your integration needs a user to perform one of these critical actions:

Sign Contract

Redirect the buyer or seller to sign the escrow contract on dhmad.tn. Standard mode only.

Accept & Pay

Redirect the buyer to accept the contract and complete payment.

Complete

Redirect the buyer to release funds to the seller. Valid from paid or delivered — deliver is not required first. Standard and quick modes (not instant).

Dispute

Redirect either party to open a dispute on the escrow.

Request Cancellation

Redirect the buyer to request cancellation of a paid or delivered escrow. Requires seller acceptance before funds are returned.

Cancel Escrow

Redirect the seller to cancel a paid or delivered escrow immediately. Refunds the buyer when applicable — no counterparty approval needed.

Reject Cancellation

Redirect the seller to reject a pending buyer cancellation request.

Accept Cancellation

Redirect the seller to accept a pending buyer cancellation request and finalize the refund.

Add Funds

Redirect the buyer to add more wallet funds into a paid or delivered escrow (fees apply to the added amount only). Not available for guest-checkout escrows.

Refund Funds

Redirect the seller to refund part or all of the remaining ledger balance to the buyer’s wallet. Refunding the full remaining balance cancels the escrow. Not available for guest-checkout escrows.

Approve Release

Redirect the client to approve a payout request on a progressive-release escrow, releasing that billing period now. Pass metadata.requestId.

Reject Release

Redirect the client to reject a payout request. Opens a dispute for that period only; the amount stays reserved and later periods keep running. Pass metadata.requestId.

​
How the Flow Works

  1. Create a session via API — Call POST /api/v1/escrows/:id/sessions with the action type, target user email, and your redirect URL. You receive a sessionId and url.
  2. Redirect the user — Send the user to https://dhmad.tn/checkout/:sessionId (or your sandbox URL for testing).
  3. User performs the action — The user logs in (if needed), sees the escrow context, and completes the action on dhmad.tn.
  4. User is redirected back — DHMAD redirects the user to your redirectUrl with query parameters: session_id and status (e.g., completed, expired, cancelled).
The redirect URL parameters (session_id, status) are informational. Treat webhooks as the source of truth for escrow state changes. Use the redirect to update your UI and optionally call GET /api/v1/sessions/:sessionId to verify the session status.

​
Security

30-Minute Expiry

Sessions expire 30 minutes after creation. Expired sessions cannot be used.

Single-Use

Each session can only be completed once. After completion, the session is marked as used.

User Email Validation

Escrow sessions require the signed-in user to match targetUserEmail. Charge checkout URLs have no target email — anyone with the link can pay.

HTTPS Enforcement

Redirect URLs must use HTTPS in production. http://localhost is allowed for development.

Redirect URL Validation

Redirect URLs must be pre-configured in your developer dashboard. No arbitrary URLs are accepted.

​
Webhook as Source of Truth

When a user completes an action via a Checkout Session, DHMAD emits webhooks for the underlying escrow events (e.g., contract.signed, escrow.paid, escrow.completed, escrow.funds.added, escrow.funds.refunded, escrow.release_request.approved, escrow.release_request.disputed). Always process webhooks to update your backend state. The redirect parameters are useful for immediate UI feedback but should not be the sole basis for state changes.
Configure allowed redirect URLs in your Developer Dashboard settings before creating checkout sessions. Requests with unconfigured or mismatched redirect URLs will fail with a 400 error.