Quickstart

Before you start

Get your base URL

Given at onboarding. It is written {BASE_URL} throughout these docs. Every path starts with /api/v1.

Create an API key

In your merchant dashboard. Use pk_test_… for test and pk_live_… for live. A new key must be approved first.

Configure your webhook

Set a webhook URL and copy the signing secret in the dashboard API settings. The signing secret is not your API key.

1. Register a payment

curl -X POST "{BASE_URL}/api/v1/payments" \
  -H "x-api-key: $MIZANIYA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1500000,
    "currency": "DZD",
    "reference": "COMMANDE-2024-8756",
    "language": "fr",
    "successUrl": "https://shop.example.dz/orders/8756/paid",
    "failureUrl": "https://shop.example.dz/orders/8756/retry",
    "metadata": { "customerId": "C-1029" }
  }'

const res = await fetch(`${process.env.MIZANIYA_BASE_URL}/api/v1/payments`, {
  method: 'POST',
  headers: {
    'x-api-key': process.env.MIZANIYA_API_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 1500000, // 15,000 DA in centimes
    currency: 'DZD',
    reference: 'COMMANDE-2024-8756',
    language: 'fr',
    successUrl: 'https://shop.example.dz/orders/8756/paid',
    failureUrl: 'https://shop.example.dz/orders/8756/retry',
    metadata: { customerId: 'C-1029' },
  }),
});
const { data } = await res.json();

amount is in centimes. To charge 1,500 DA send 150000; for 1,499.50 DA send 149950.

2. Store the id and redirect the payer

The response contains the payment id and the checkoutUrl:

{
  "statusCode": 201,
  "message": "Payment registered successfully.",
  "data": {
    "id": "6c1d9a3e-2f0b-4a7e-9d51-0b3a7c2e9f14",
    "reference": "COMMANDE-2024-8756",
    "amount": 1500000,
    "fees": 150,
    "total": 1515000,
    "currency": "DZD",
    "language": "fr",
    "status": "created",
    "expiresAt": "2026-08-02T12:15:00.000Z",
    "checkoutUrl": "https://checkout.mizaniyapay.com/9f1c…?lang=fr"
  }
}

Store the id, you need it for every later call. The checkoutUrl is shown only once: redirect the payer straight away.

3. The payer pays

On our hosted page the payer enters their card details, then the OTP sent by SMS from their bank. In test mode, use the test cards and OTP codes.

4. Receive the webhook

When the payment reaches a status you must act on, we POST to your webhook URL. Verify the signature and process the event once, using deliveryId.

5. Fulfil the order

Ship the order only when payment.status is success. You can double-check with Get a payment.

When the payer comes back to your successUrl or failureUrl, we append reference=<your reference> and keep your own query parameters. Do not treat the redirect as proof of payment: rely on the webhook or GET /payments/{id}.

Getting Started

Core Concepts

Webhooks

Testing

Before you start

1. Register a payment

2. Store the id and redirect the payer

3. The payer pays

4. Receive the webhook

5. Fulfil the order

​Before you start

​1. Register a payment

​2. Store the id and redirect the payer

​3. The payer pays

​4. Receive the webhook

​5. Fulfil the order

Before you start

1. Register a payment

2. Store the id and redirect the payer

3. The payer pays

4. Receive the webhook

5. Fulfil the order