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.

API Explorer interactif

Testez les endpoints réellement déployés depuis cette page. La liste est générée à partir de la description OpenAPI servie par la plateforme, elle reste donc toujours synchronisée avec les routes disponibles. Utilisez une clé test : elle n'est jamais enregistrée ni transmise ailleurs que vers l'API DIGIBA.

curl -X GET "/api/public/v1/health"

Spécification téléchargeable : /api/public/v1/openapi.json — importable dans Postman, Insomnia ou un générateur de SDK.

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.processing, payment.success, payment.failed, payment.cancelled, payment.expired, payment.succeeded (checkout hébergé)
• 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 (même identifiant à chaque rejeu).
• Répondez 2xx rapidement ; les échecs sont réessayés (3 tentatives puis rejeu manuel possible depuis la console).

Vérification de statut & polling

Un webhook provider n'est qu'un indice : DIGIBA PAYMENT CORE re-interroge toujours l'API du provider avant de changer un statut. Aucun paiement n'est marqué success sans confirmation officielle du provider.

• Machine d'état : created → processing → success / failed / cancelled / expired. Un statut terminal n'est jamais réécrit.
• unknown signifie « statut temporairement indéterminé » et ne vaut jamais un succès.
• Rythme de vérification : T+0, T+10s, T+30s, T+60s, T+2min, T+5min, plafonné à 40 tentatives (jamais de boucle infinie).
• Côté marchand, interrogez GET /v1/payments/{ref} : le Core rafraîchit auprès du provider selon ce rythme (ajoutez ?refresh=false pour lire le cache).

# Vérification de statut (source de vérité)
curl https://payment.digiba.tech/api/public/v1/payments/DIGIBA20260824X175SA \
  -H "Authorization: Bearer $DIGIBA_API_KEY"

# Réponse
{ "success": true, "data": { "reference": "DIGIBA20260824X175SA",
  "status": "processing", "provider": "pawapay", "provider_status": "PENDING" } }

Guide d'intégration (DIGIBA MARKET & autres)

1. Créez le projet dans la console et récupérez une clé API TEST.
2. Créez le paiement côté serveur (jamais depuis le navigateur) avec un Idempotency-Key propre à la commande.
3. Redirigez le client vers l'URL de checkout hébergée retournée par le Core.
4. Renseignez votre URL de webhook + secret dans la console, puis mettez à jour la commande uniquement sur payment.success reçu et signé, ou après un GET /v1/payments/{ref} retournant success.
5. Ne considérez jamais un retour navigateur (return_url) comme une preuve de paiement : le frontend ne décide jamais du statut.
6. Passez en clé LIVE seulement après un test complet en environnement TEST.

// Exemple Lovable / Supabase (server function)
const res = await fetch("https://payment.digiba.tech/api/public/v1/payments", {
  method: "POST",
  headers: {
    "authorization": `Bearer ${process.env.DIGIBA_API_KEY}`,
    "content-type": "application/json",
    "idempotency-key": `order_${orderId}`,
  },
  body: JSON.stringify({
    amount: 20, currency: "USD", action: "C2B",
    mobileMoney: "243812345678", customerReference: orderId,
    description: "Commande DIGIBA MARKET",
  }),
});
const { data } = await res.json(); // data.reference = RefTransa

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.