API Overview

​

Base URL

• Production: https://dhmad.tn/api/v1
• Sandbox (for testing): https://sandbox.dhmad.tn/api/v1 — use sk_sandbox_ keys; see Sandbox

​

Authentication

• Bearer Token: Authorization: Bearer sk_live_your_api_key_here
• X-API-Key Header: X-API-Key: sk_live_your_api_key_here

​

Interactive API Explorer

• Browse all available endpoints
• View request/response schemas
• Test API calls directly from your browser
• See example requests and responses (including Quick Escrow with Proof on POST /v1/escrows)
• Authenticate with your API key

​

Available Endpoints

​

Account & Authentication

• GET /me - Get API key information — verify your API key and get developer account details
• GET /balance - Get user balance — available, pending, and escrow balances

​

Escrows

• Overview — Introduction to escrows, modes (standard, quick, instant), Quick Escrow with Proof, statuses, and lifecycle
• POST /escrows - Create a new escrow
• GET /escrows - List escrows (with pagination and filters)
• GET /escrows/:id - Get escrow details
• GET /escrows/:id/proof - Get escrow proof — viewable proof URLs for Quick Escrow with Proof
• GET /escrows/:id/contract - Get contract — retrieve contract details and PDF
• PUT /escrows/:id - Update escrow — update a pending escrow
• POST /escrows/:id/deliver - Deliver escrow — seller marks as delivered
• POST /escrows/:id/reject-delivery - Reject delivery — buyer returns escrow to paid
• POST /escrows/:id/cancel - Cancel escrow — cancel a pending escrow

​

Checkout Sessions

• Overview — How checkout sessions work, security, and supported actions
• POST /escrows/:id/sessions - Create checkout session — create a session and get a redirect URL
• GET /sessions/:sessionId - Get checkout session — verify session status after redirect

​

Identity Verifications

• Overview — Pre-account KYC flow, sandbox behavior, and constraints
• POST /identity-verifications - Create verification — start KYC and send invite email
• GET /identity-verifications/:id - Get verification — poll status
• GET /identity-verifications?email= - List by email

​

OAuth 2.0

• GET /api/oauth/authorize - Authorization endpoint — redirect users to authenticate
• POST /api/oauth/token - Token endpoint — exchange authorization code for tokens
• GET /api/oauth/userinfo - UserInfo endpoint — get authenticated user profile

​

Webhooks (Developer Portal Authentication)

• POST /api/developer/webhooks - Create webhook
• GET /api/developer/webhooks - List webhooks
• GET /api/developer/webhooks/:id - Get webhook
• PUT /api/developer/webhooks/:id - Update webhook
• POST /api/developer/webhooks/:id/regenerate-secret - Regenerate secret
• DELETE /api/developer/webhooks/:id - Delete webhook

​

Response Format

{
  "data": { ... }
}

{
  "message": "Success message",
  "escrow": { ... },
  "url": "...",
  "trackingId": "..."
}

{
  "error": "Error type",
  "message": "Human-readable error description"
}

​

Status Codes

• 200 - Success
• 201 - Created
• 400 - Bad Request
• 401 - Unauthorized
• 403 - Forbidden
• 404 - Not Found
• 429 - Too Many Requests
• 500 - Internal Server Error

​

Rate Limiting

• Default: 100 requests per minute per IP address
• Header: Rate limit information is included in response headers
• Exceeding: Returns 429 Too Many Requests

​

Pagination

GET /escrows?page=1&limit=20

{
  "escrows": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}

​

Escrow Modes

​

Escrow Statuses