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" },
    "enabledPaymentMethods": ["paypal_card", "d17", "virement_bancaire"]
  }'

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',
    enabledPaymentMethods: ['paypal_card', 'd17', 'virement_bancaire']
  })
});

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',
        'enabledPaymentMethods': ['paypal_card', 'd17', 'virement_bancaire']
    }
)

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"
  }
}

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" },
    "enabledPaymentMethods": ["paypal_card", "d17", "virement_bancaire"]
  }'

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',
    enabledPaymentMethods: ['paypal_card', 'd17', 'virement_bancaire']
  })
});

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',
        'enabledPaymentMethods': ['paypal_card', 'd17', 'virement_bancaire']
    }
)

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 and no completionDeadlineDays. Subscribe to charge.status.updated (see Webhooks). Do not pass this id to /v1/escrows/:id — GET returns 404; deliver, sessions, and other escrow actions return 409 CHARGE_NOT_AN_ESCROW.

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" },
    "enabledPaymentMethods": ["paypal_card", "d17", "virement_bancaire"]
  }'

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',
    enabledPaymentMethods: ['paypal_card', 'd17', 'virement_bancaire']
  })
});

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',
        'enabledPaymentMethods': ['paypal_card', 'd17', 'virement_bancaire']
    }
)

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.

string

Who pays the DHMAD fees: seller (default) or buyer. With seller, the payer pays amount and the fees come out of what you receive. With buyer, the fees are added on top of amount and the payer pays both.

array

The payment methods the checkout offers for this charge. Omit it, or send an empty array, to offer every method. Allowed values:

paypal_card: debit or credit card, processed by PayPal
paypal: PayPal account
apple_pay: Apple Pay
d17: D17 transfer, with a proof of payment
flouci: Flouci transfer, with a proof of payment
virement_bancaire: bank transfer, with a proof of payment
cash_collection: cash handed to a courier at the payer’s address

Any other value is rejected with 400.The list only narrows what checkout would offer anyway. Card, PayPal and Apple Pay need the charge to reach the PayPal minimum, and Apple Pay also needs a supported device and browser. Cash collection is only for TND charges paid from Tunisia, within the courier’s amount limits. A payer who is signed in to DHMAD can always pay from their DHMAD wallet.

If none of the methods you list can be offered for a charge (for example only paypal on a charge below the PayPal minimum), a payer without DHMAD wallet funds has no way to pay. Keep a transfer method such as virement_bancaire in the list.

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