Documentation développeur

Authentification

Chaque requête serveur-à-serveur utilise votre clé API en Bearer. La clé n'est affichée qu'une seule fois à la création ou à la rotation ; seul son hash SHA-256 est stocké. Les scopes et l'éventuelle liste d'IP autorisées sont vérifiés côté backend.

Authorization: Bearer dgb_test_xxxxxxxxxxxxxxxx
Content-Type: application/json
Idempotency-Key: <uuid unique par tentative>

• payments:create — créer un paiement ou une session checkout
• payments:read — lire un paiement
• transactions:read — lister les transactions

Ne mettez jamais une clé API dans une application mobile, un front-end ou un dépôt public. Utilisez DIGIBA CHECKOUT pour les paiements initiés par un navigateur.

Environnements

L'environnement est porté par la clé API (test ou live), pas par le corps de la requête. Une clé test ne peut jamais toucher de l'argent réel.

API Paiements

POST /payments

curl -X POST https://payment.digiba.tech/api/public/v1/payments \
  -H "Authorization: Bearer $DIGIBA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6f1c2f7a-0f5b-4b9c-9a1e-2f0d7c3b1a44" \
  -d '{
    "amount": 2500,
    "currency": "CDF",
    "action": "C2B",
    "mobileMoney": "0812345678",
    "description": "Recharge compte",
    "customerReference": "CLIENT-4471"
  }'

{
  "success": true,
  "data": {
    "refTransa": "DIGIBA20260214A7F3Q1",
    "status": "pending",
    "amount": 2500,
    "fee": 0,
    "commission": 0,
    "totalAmount": 2500,
    "currency": "CDF",
    "mobileMoney": "081****678",
    "environment": "test"
  }
}

GET /payments/{refTransa}

Rafraîchit le statut auprès du provider si la transaction n'est pas encore terminale. Le statut renvoyé est toujours celui vérifié côté serveur.

curl https://payment.digiba.tech/api/public/v1/payments/DIGIBA20260214A7F3Q1 \
  -H "Authorization: Bearer $DIGIBA_API_KEY"

GET /payments

curl "https://payment.digiba.tech/api/public/v1/payments?status=success&limit=25&offset=0" \
  -H "Authorization: Bearer $DIGIBA_API_KEY"

Statuts possibles : created, processing, pending, success, failed, cancelled, expired, unknown. Un statut provider inconnu ne devient jamais success.

DIGIBA CHECKOUT (page hébergée)

Votre serveur crée une session, puis redirige le client vers l'URL de checkout hébergée par DIGIBA. Le montant, la devise et le marchand sont figés côté serveur à la création : la page ne les accepte jamais depuis le navigateur.

POST /checkout/sessions

curl -X POST https://payment.digiba.tech/api/public/v1/checkout/sessions \
  -H "Authorization: Bearer $DIGIBA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 9d1f0b2e-77ab-4a3f-8f0f-1b9a5c7e2d10" \
  -d '{
    "amount": 15000,
    "currency": "CDF",
    "description": "Réservation #A-2291",
    "customer": { "name": "Client DIGIBA", "phone": "0812345678" },
    "return_url": "https://marchand.com/paiement/succes",
    "cancel_url": "https://marchand.com/paiement/annule",
    "expires_in_minutes": 30
  }'

{
  "success": true,
  "data": {
    "session_id": "cs_test_...",
    "payment_id": "pay_test_...",
    "checkout_url": "https://payment.digiba.tech/checkout/cs_test_...",
    "status": "created",
    "expires_at": "2026-02-14T12:30:00.000Z"
  }
}

GET /checkout/sessions/{session_id}

curl https://payment.digiba.tech/api/public/v1/checkout/sessions/cs_test_... \
  -H "Authorization: Bearer $DIGIBA_API_KEY"

Réseaux Mobile Money supportés : Vodacom M-Pesa, Airtel Money, Orange Money. Le client saisit son numéro sur la page DIGIBA, valide sur son téléphone, puis obtient un reçu téléchargeable. Ne considérez jamais le retour navigateur comme une preuve de paiement : fiez-vous au webhook ou à l'API.

Webhooks signés

Configurez votre URL HTTPS et générez votre secret dans la console (onglet Checkout). Chaque livraison est signée HMAC-SHA256 et porte un identifiant d'événement unique pour la protection contre les rejeux.

POST https://marchand.com/api/webhooks/digiba-payment
X-Digiba-Event: payment.succeeded
X-Digiba-Event-Id: evt_...
X-Digiba-Timestamp: 1771070400
X-Digiba-Signature: sha256=<hex>

{
  "event": "payment.succeeded",
  "session_id": "cs_live_...",
  "payment_id": "pay_live_...",
  "reference": "DIGIBA20260214A7F3Q1",
  "amount": 15000,
  "currency": "CDF",
  "status": "success",
  "network": "vodacom",
  "paid_at": "2026-02-14T12:04:11.000Z"
}

// Vérification (Node.js)
import { createHmac, timingSafeEqual } from "crypto";

const signed = `${timestamp}.${rawBody}`;
const expected = createHmac("sha256", process.env.DIGIBA_WEBHOOK_SECRET)
  .update(signed)
  .digest("hex");

const a = Buffer.from(signature.replace("sha256=", ""));
const b = Buffer.from(expected);
const valid = a.length === b.length && timingSafeEqual(a, b);

• Événements : payment.succeeded, payment.failed, payment.expired
• Rejetez une signature invalide ou un horodatage de plus de 5 minutes.
• Traitez les événements de façon idempotente via X-Digiba-Event-Id.
• Répondez 2xx rapidement ; les échecs sont réessayés.

Codes d'erreur

{
  "success": false,
  "error": { "code": "PROVIDER_NOT_CONFIGURED", "message": "Le provider n'est pas configuré." }
}

Règles & limites

• Référence DIGIBA : 20 caractères, générée par le serveur, unique.
• Numéro Mobile Money : exactement 10 chiffres ; toujours masqué dans les réponses et les journaux.
• Devises : CDF et USD, selon l'autorisation du projet.
• B2C (payout) désactivé par défaut ; renvoie ACTION_NOT_ALLOWED.
• Rate limit configurable par projet (60 requêtes/minute par défaut).
• Sessions de checkout : 30 minutes par défaut, à usage unique.
• Les callbacks provider sont des indices : le statut final est toujours vérifié par DIGIBA.