Create Charge

curl -X POST https://dhmad.tn/api/v1/charges \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "500 credits",
    "amount": 120,
    "currency": "TND",
    "merchantReference": "purchase_65f1c2a9b1",
    "redirectUrl": "https://myapp.com/billing/callback",
    "receiptEmail": "customer@example.com",
    "metadata": { "plan": "credits_500" }
  }'

const response = await fetch('https://dhmad.tn/api/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: '500 credits',
    amount: 120,
    currency: 'TND',
    merchantReference: 'purchase_65f1c2a9b1',
    redirectUrl: 'https://myapp.com/billing/callback',
    receiptEmail: 'customer@example.com'
  })
});

const { charge } = await response.json();

import requests

response = requests.post(
    'https://dhmad.tn/api/v1/charges',
    headers={
        'Authorization': 'Bearer sk_live_your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'title': '500 credits',
        'amount': 120,
        'currency': 'TND',
        'merchantReference': 'purchase_65f1c2a9b1',
        'redirectUrl': 'https://myapp.com/billing/callback',
        'receiptEmail': 'customer@example.com'
    }
)

charge = response.json()['charge']

{
  "charge": {
    "id": "507f1f77bcf86cd799439011",
    "merchantReference": "purchase_65f1c2a9b1",
    "status": "pending",
    "title": "500 credits",
    "amount": 120,
    "currency": "TND",
    "amountTnd": 120,
    "receiptEmail": "customer@example.com",
    "paidAt": null,
    "completedAt": null,
    "createdAt": "2026-01-15T10:00:00Z",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://dhmad.tn/checkout/550e8400-e29b-41d4-a716-446655440000",
    "expiresAt": "2026-01-15T11:00:00Z"
  }
}

Create a charge and get a public checkout URL. There is no buyerEmail: anyone who opens the URL can pay it, and DHMAD collects a receipt email from them at checkout. Payment completes the charge and settles the funds into your business wallet in one step — there is no deliver call.

Configure allowed redirect URLs in your Developer Dashboard before creating charges. A redirectUrl that does not match one of them is rejected with 400.

curl -X POST https://dhmad.tn/api/v1/charges \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "500 credits",
    "amount": 120,
    "currency": "TND",
    "merchantReference": "purchase_65f1c2a9b1",
    "redirectUrl": "https://myapp.com/billing/callback",
    "receiptEmail": "customer@example.com",
    "metadata": { "plan": "credits_500" }
  }'

const response = await fetch('https://dhmad.tn/api/v1/charges', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_your_api_key_here',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: '500 credits',
    amount: 120,
    currency: 'TND',
    merchantReference: 'purchase_65f1c2a9b1',
    redirectUrl: 'https://myapp.com/billing/callback',
    receiptEmail: 'customer@example.com'
  })
});

const { charge } = await response.json();

import requests

response = requests.post(
    'https://dhmad.tn/api/v1/charges',
    headers={
        'Authorization': 'Bearer sk_live_your_api_key_here',
        'Content-Type': 'application/json'
    },
    json={
        'title': '500 credits',
        'amount': 120,
        'currency': 'TND',
        'merchantReference': 'purchase_65f1c2a9b1',
        'redirectUrl': 'https://myapp.com/billing/callback',
        'receiptEmail': 'customer@example.com'
    }
)

charge = response.json()['charge']

{
  "charge": {
    "id": "507f1f77bcf86cd799439011",
    "merchantReference": "purchase_65f1c2a9b1",
    "status": "pending",
    "title": "500 credits",
    "amount": 120,
    "currency": "TND",
    "amountTnd": 120,
    "receiptEmail": "customer@example.com",
    "paidAt": null,
    "completedAt": null,
    "createdAt": "2026-01-15T10:00:00Z",
    "sessionId": "550e8400-e29b-41d4-a716-446655440000",
    "url": "https://dhmad.tn/checkout/550e8400-e29b-41d4-a716-446655440000",
    "expiresAt": "2026-01-15T11:00:00Z"
  }
}

Request Body

string

required

What the payer is paying for. Shown on checkout and on the receipt.

number

required

Amount in the face currency.

string

TND, USD, or EUR. Defaults to TND. Non-TND charges are converted for the internal ledger; the payer is charged the face amount.

string

required

Your own opaque identifier for what is being bought — an order id, a purchase row id, anything you can look up later. Unique per developer and used as the idempotency key. Letters, digits, and . _ : -, up to 200 characters.

string

required

Where the payer returns after paying or abandoning. Must match an allowed redirect URL and use HTTPS (except http://localhost).

string

Prefills the receipt field on checkout. The payer can change it, so never treat it as the identity of the buyer.

object

Key-value pairs (strings only, 500 characters or less per value) carried on the checkout session.

Response Fields

Repeat requests

Calling this endpoint again with a merchantReference you already used returns 200 with the original charge instead of 201, so a retry after a timeout is safe. Use the same call to reissue an expired checkout URL for an abandoned payment.

Errors

Status	When
400	Invalid body, `redirectUrl` not allowed or not HTTPS, or the amount is below the minimum.
403	The developer account has no business account, or the business has not passed KYB in live mode.
429	Daily escrow/charge creation limit reached.
502	Currency conversion failed. Retry, or charge in TND.

Get Started

API Reference

Guides

Developer Portal

Request Body

Response Fields

Repeat requests

Errors

​Request Body

​Response Fields

​Repeat requests

​Errors

Request Body

Response Fields

Repeat requests

Errors