Introduction

This section describes the Dzwallet payment gateway API.

The Dzwallet API is simple to integrate into your company's software. Our API takes cURL requests, has well-formatted URLs, and produces JSON responses.

The API can be used in test mode without affecting your real data. The request is authenticated using the API key, which also establishes whether the payment is legitimate or not. For test mode just use the sandbox URL and In case of live mode use the live URL from section Initiate Payment .

Supported Currencies

The supported currencies by Dzwallet are given below.

Supported Payment Gateway

Accept CIB and EDAHABIA payments in DZD through SATIM.

Get The Api Key

How to obtain the api key is explained in this part.

To access your Dzwallet merchant account, please log in. In case you don't have an account, you can click here.

Now go to the Account > Settings > API Key from the merchant panel.

The api keys can be found there which is Public key and Secret key. Use these keys to initiate the API request. Every time you can generate new API key by clicking Generate Api Key button. Remember do not share these keys with anyone.

Domains and URL Rules

Register your website before accepting payments.

Before you can initiate a payment you must register the domain(s) of your website in Profile Setting > Your website domains. Enter one domain per line, for example example.com. You can register up to 10 domains. Subdomains are accepted automatically (shop.example.com is covered by example.com).

Every one of ipn_url, success_url and cancel_url must:

• start with http:// or https:// (https is strongly recommended);
• belong to one of your registered domains (the host equals the domain or is a subdomain of it);
• be publicly reachable: localhost, .local, .internal and private or reserved IP addresses are rejected;
• not contain a username or password, and use only the ports 80, 443, 8080 or 8443;
• be at most 500 characters long.

The same rules apply to site_logo (public http/https url, but it does not have to be on your domain).

Related error messages:

Initiate Payment

In this section, the procedure for initiating the payment is explained.

To begin the payment process, use the sample code provided, and pay close attention to the parameters. The API endpoints mentioned below will need to be used to make the request.

Live End Point: https://dzwallet.app/payment/initiate

Test End Point: https://dzwallet.app/test/payment/initiate

Request to the end point with the following parameters below.

Validate The Payment and IPN

This section describes the process to get your instant payment notification.

To initiate the payment follow the example code and be careful with the perameters. You will need to make request with these following API end points.

End Point: Your business application ipn url.

Request Method: POST

You will get following parameters below.

IPN Security and Delivery

How to trust and handle the notification.

Every notification is signed. Verify the signature on the raw request body before you trust anything in it.

Headers

The body also contains event (payment.succeeded), event_id and timestamp, next to the fields described above.

How to verify a notification

1. Read the raw body exactly as received, before any parsing.
2. Compute HMAC-SHA256 of the timestamp, a dot and the raw body, with your secret key (the test secret for test payments, the live secret for live payments). Compare it with v1 using a constant-time comparison.
3. Reject the notification if its timestamp is more than 5 minutes away from your server time.
4. Read the event_id field of the body (it is signed; do not use the header for this). If you already processed it, answer 200 and do nothing. Otherwise store it, with a unique constraint, before you fulfil the order.
5. Check that the identifier and the amount match your own order, then fulfil the order once.
6. Answer with a 2xx status quickly.

Delivery and retries

• The notification is sent only after the payment gateway has confirmed the payment. It is a POST request to your ipn_url with a 15 second timeout; redirects are not followed.
• If your endpoint does not answer with a 2xx status, we retry with increasing delays: 1, 2, 4, 8, 16 and 32 minutes, then every hour, for up to 15 attempts (about 12 hours). Every retry has a new timestamp and signature but the same event id.
• If all attempts fail, confirm the payment with the Payment Status endpoint below.
• Every delivery attempt (status code, time, errors) is listed in your merchant dashboard under Webhook Log, where you can also send a notification again with the Resend button. A resent notification has the same event id.
• Never rely on the customer reaching your success_url. Redirects can be reached or faked by anyone; only the signed notification, or a call to the Payment Status endpoint, proves a payment.
• Use a valid HTTPS certificate on your ipn_url so the notification is delivered securely.

Older signature field. The signature field in the body (uppercase HMAC-SHA256 of data.amount and identifier, with your secret key) is still sent so existing integrations keep working. It does not cover the timestamp and cannot stop replays, so use the header in new integrations.

PHP

<?php
$raw       = file_get_contents('php://input');          // exact body, before any parsing
$header    = $_SERVER['HTTP_X_DZWALLET_SIGNATURE'] ?? '';
$eventId   = $_SERVER['HTTP_X_DZWALLET_EVENT_ID'] ?? '';
$secret    = 'YOUR_SECRET_KEY';                         // test secret for test payments

parse_str(str_replace(',', '&', $header), $h);       // t=..., v1=...
$t = (int) ($h['t'] ?? 0);
$expected = hash_hmac('sha256', $t . '.' . $raw, $secret);

if (!hash_equals($expected, strtolower($h['v1'] ?? ''))) { http_response_code(400); exit; }
if (abs(time() - $t) > 300)                              { http_response_code(400); exit; }
parse_str($raw, $p);                                     // the event id comes from the signed body
$eventId = $p['event_id'] ?? '';
if (already_processed($eventId))                         { http_response_code(200); exit; }

// check $p['identifier'] and $p['data']['amount'] against your order
mark_processed($eventId);
fulfil_order($p['identifier']);
http_response_code(200);

Node.js

// Express: keep the raw body
app.post('/dzwallet/ipn', express.raw({ type: '*/*' }), (req, res) => {
  const raw = req.body.toString('utf8');
  const header = req.get('X-DzWallet-Signature') || '';
  const parts = Object.fromEntries(header.split(',').map(s => s.trim().split('=')));
  const t = parseInt(parts.t, 10);
  const expected = require('crypto').createHmac('sha256', SECRET)
    .update(t + '.' + raw).digest('hex');
  const ok = parts.v1 && parts.v1.length === expected.length &&
    require('crypto').timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected));
  if (!ok || Math.abs(Date.now() / 1000 - t) > 300) return res.sendStatus(400);
  const eventId = new URLSearchParams(raw).get('event_id');   // from the signed body, not the header
  if (alreadyProcessed(eventId)) return res.sendStatus(200);
  markProcessed(eventId);          // unique constraint on event_id
  // parse raw with new URLSearchParams(raw), check identifier and amount, fulfil once
  res.sendStatus(200);
});

Python

import hmac, hashlib, time

def verify(raw_body: bytes, header: str, secret: str, tolerance=300) -> bool:
    parts = dict(p.strip().split('=', 1) for p in header.split(','))
    t = int(parts['t'])
    expected = hmac.new(secret.encode(), (str(t) + '.').encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts['v1'].lower()) and abs(time.time() - t) <= tolerance

# Flask: raw = request.get_data(); header = request.headers['X-DzWallet-Signature']
# Then: parse the body (urllib.parse.parse_qs), skip if its event_id was already stored, check identifier and amount, fulfil once.

The official SDKs do all of this for you: see the Developers page.

Payment Status

Check a payment at any time from your server.

End Point: https://dzwallet.app/api/payment/status   Method: POST

Use it to confirm a payment if your IPN did not arrive. A live public key returns only live payments; a test public key returns only test payments. Use a unique identifier for each order within its mode. If you reuse an identifier, the latest checkout attempt in that mode is returned.

Possible payment_status values: initiated, pending, success, rejected, cancelled. Only success means the money was received. A successful response also returns identifier, amount, currency, trx and created_at. Errors return {"status":"error","message":"Invalid API key"} or "Payment not found".

Refunds

How refunds work.

• Refunds are requested from your merchant dashboard (Refunds). There is no refund API call.
• For CIB / EDAHABIA payments our commission (gateway charge and payment charge) is not refunded: the customer receives the payment amount minus these fees, and your balance is debited by the same refunded amount.
• After the request is approved by our team it is processed immediately through the same gateway that took the payment: CIB / EDAHABIA payments are refunded through SATIM.
• If the payment was already released to your balance, the refunded amount is debited from your merchant balance, so your balance must cover it. A payment can be refunded only once.
• After a refund the payment status becomes refunded and the customer is credited by the card network according to the bank timelines.

Fees and Settlement

What you receive and when.

• Your balance is credited with the full payment amount, then the gateway fee and service charge are deducted as separate transactions, so each one is visible in your transaction history.
• Funds are released to your balance after the hold period configured on your account.

Rate Limits

Keep your requests reasonable.

Initiate Payment (live and test) and Payment Status are limited to 60 requests per minute per IP address. Exceeding it returns HTTP 429 Too Many Requests; wait a minute and retry. Always send API requests from your server, never from the visitor browser, so your secret key stays private.

Common Errors

Messages returned by Initiate Payment.