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 but the buyer still confirms after delivery; in instant mode only accept_pay is used and completion happens when you call the deliver endpoint.

​
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 mark the escrow as complete and release funds to the seller. 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.

​
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

Only the user whose email matches targetUserEmail can complete the session.

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