Skip to main content
DHMAD provides a sandbox environment so you can test escrow creation, payments, and the full API without touching production data or real money.

​
What is the Sandbox?

The sandbox is a separate deployment of the DHMAD platform:
  • Frontend: sandbox.dhmad.tn — same UI as production, with a clear “Sandbox environment” banner at the top
  • API: https://sandbox.dhmad.tn/api — same endpoints and behavior as production
  • Developer portal: developer.dhmad.tn — create and manage sandbox API keys (sk_sandbox_...)

Production

dhmad.tn — Live data, real transactions. Use sk_live_ API keys.

Sandbox

sandbox.dhmad.tn — Test data only. Use sk_sandbox_ API keys.

​
Why Use the Sandbox?

  • Safe testing — Create escrows, simulate payments, and run full flows without affecting production
  • Integration development — Build and debug your integration before going live
  • No impact on production — Sandbox uses a separate database; production data and balances are never touched
  • Same API — Endpoints, request/response formats, and behavior match production

​
API Keys: Live vs Sandbox

API keys are environment-specific. You must use the correct key for the API you are calling.
EnvironmentKey prefixUse with API
Livesk_live_...https://dhmad.tn/api (production)
Sandboxsk_sandbox_...https://sandbox.dhmad.tn/api (sandbox)
Keys and environments do not mix.
  • A sk_live_ key on the sandbox API returns 401 with a message to use a sandbox key.
  • A sk_sandbox_ key on the production API returns 401 with a message to use a live key.

​
Getting Sandbox API Keys

  1. Open the developer portal: developer.dhmad.tn
  2. Sign up or log in
  3. Associate your developer account with a user account (use a test user on sandbox.dhmad.tn)
  4. Go to API Keys and click Create API Key
  5. Select Sandbox as the environment when creating the key. Keys created with the sandbox environment are sandbox keys (sk_sandbox_...). Use them only with https://sandbox.dhmad.tn/api.
Sandbox and production have separate accounts and data. You need a user account on sandbox.dhmad.tn to test with sandbox API keys, but you create the sandbox API keys in the regular developer portal at developer.dhmad.tn.

​
Sandbox Base URL

Use this base URL for all sandbox API requests: 
https://sandbox.dhmad.tn/api
The API lives under /api; for the v1 API the path is /api/v1. For example:
  • Balance: GET https://sandbox.dhmad.tn/api/v1/balance
  • Create escrow: POST https://sandbox.dhmad.tn/api/v1/escrows
  • List escrows: GET https://sandbox.dhmad.tn/api/v1/escrows

​
Example: First Sandbox Request

After you have a sandbox API key: 
curl -X GET "https://sandbox.dhmad.tn/api/v1/balance" \
  -H "Authorization: Bearer sk_sandbox_your_key_here" \
  -H "Content-Type: application/json"

{
  "balance": {
    "available": 0,
    "pending": 0,
    "escrow": 0
  }
}

​
Data and Behaviour

  • Separate database — Escrows, users, balances, and API keys in the sandbox are completely separate from production. Nothing you do in the sandbox affects production.
  • Same features — Escrow creation, payments, contracts, webhooks, and the rest of the API behave the same. Use the sandbox to validate your integration end-to-end.
  • Test data — Use test users, test emails, and test payment methods. No real money or production credentials.

​
Sandbox Banner (Frontend)

On sandbox.dhmad.tn, a sticky banner at the top of the page indicates:
Sandbox environment — for testing only. Data and transactions are not production.
This helps avoid confusion with the live site.

​
Switching from Sandbox to Production

When you are ready to go live:
  1. Get live API keys from the production developer portal: developer.dhmad.tn
  2. Change your app’s API base URL from https://sandbox.dhmad.tn/api to https://dhmad.tn/api
  3. Replace sk_sandbox_... with sk_live_... in your config/secrets
  4. Ensure your production developer account is associated with the correct production user account
Double-check base URL and key prefix before switching. Using a sandbox key in production (or vice versa) will result in 401 Unauthorized.

​
Configuration Reference

If you run your own frontend or developer portal against the sandbox:
AppVariableSandbox value
FrontendNEXT_PUBLIC_SANDBOXtrue (enables sandbox banner; all API/socket requests use the sandbox URL; dev/start use port 3001)
FrontendNEXT_PUBLIC_SANDBOX_API_URLhttps://sandbox.dhmad.tn/api or http://localhost:6002/api (optional; defaults to http://localhost:6002/api)
FrontendNEXT_PUBLIC_API_URLIgnored when NEXT_PUBLIC_SANDBOX=true
Developer portalNEXT_PUBLIC_SANDBOX + NEXT_PUBLIC_SANDBOX_API_URLSame as frontend when running against sandbox
BackendAPP_ENVsandbox (when set, default port is 6002 if PORT is unset)

​
Summary

TopicSandboxProduction
Frontendsandbox.dhmad.tndhmad.tn
API basehttps://sandbox.dhmad.tn/apihttps://dhmad.tn/api
Developer portaldeveloper.dhmad.tn (create sandbox keys here)developer.dhmad.tn
API key prefixsk_sandbox_sk_live_
DataTest only; separate DBLive data

​
Next Steps

Prefer the sandbox for all development and pre-launch testing. Move to production only when your integration is validated and you are ready for real users and real transactions.