Développeurs — Documentation API Djaba

Par où commencer

Conformité

API Connect

Diagnostic de conformité PI-SPI, statut d'établissement et transmission de reporting réglementaire.

Voir la référence → Encaissement

API Marchand

Paiements, liens de paiement, QR codes interopérables, demandes de paiement et retours de fonds.

Voir la référence → Intégration

Checkout intégré

Parcours de paiement embarqué sur votre site, avec widget JavaScript et session créée côté serveur.

Voir la référence →

Démarrage rapide

Toutes les requêtes sont adressées à l'API REST Djaba en HTTPS et répondent en JSON.

curl https://api.djaba.io/v1/ping \
  -H "Authorization: Bearer {votre_cle_api}"

Authentification

Chaque requête doit inclure une clé API en en-tête Authorization, selon le schéma Bearer.

Authorization: Bearer sk_test_a1b2c3d4e5f6...

Préfixe	Environnement	Disponibilité
`sk_test_`	Sandbox	Disponible dès la création de compte
`sk_live_`	Production	À l'obtention de l'agrément Djaba

Une clé sandbox se compose du préfixe sk_test_ suivi de 48 caractères hexadécimaux. Elle n'est affichée qu'une seule fois, à la génération : Djaba n'en conserve qu'une empreinte hachée. Générez la vôtre depuis vos clés API.

Standards PI-SPI

L'API Djaba est conçue en cohérence avec les spécifications de l'API Business PI-SPI de la BCEAO (Plateforme d'Interopérabilité du Système de Paiement Instantané) : mêmes conventions de pagination, même format d'erreurs, et couverture des mêmes familles de services, pour que vos équipes techniques n'aient qu'un seul modèle mental à maîtriser.

Service PI-SPI	Description
Alias de compte	Créer et gérer des alias pour simplifier les transferts entre comptes
QR Code interopérable	Générer des QR codes EMV conformes pour l'encaissement au point de vente
Paiements instantanés	Paiements immédiats, unitaires ou en masse, entre participants
Demandes de paiement (RTP)	Initier une demande de paiement pour faciliter la collecte (facturation, e-commerce)
Retours de fonds	Gérer les retours de fonds et remboursements
Demandes d'annulation	Initier ou répondre à une demande d'annulation de transaction

Pagination & filtres

Les endpoints retournant des listes suivent une structure commune avec deux sections : data (les éléments de la page) et meta (contexte de pagination).

GET /v1/payments?statut=IRREVOCABLE&sort=-dateCreation&page=1&size=20

{
  "data": [ { "id": "1234", "montant": 50000, "statut": "IRREVOCABLE" } ],
  "meta": { "total": 150, "page": 1, "size": 20, "next": 2 }
}

Opérateurs de filtre disponibles sur les champs indexés : eq, ne, gt, gte, lt, lte, in, contains, beginsWith, exists. Le tri se fait via sort=champ (croissant) ou sort=-champ (décroissant).

Gestion des erreurs

Les codes 2xx indiquent un succès, 4xx une erreur côté client, 5xx une erreur côté serveur. Le corps des réponses d'erreur suit le format standard RFC 7807 :

{
  "type": "https://api.djaba.io/errors/format-invalide",
  "title": "Format invalide",
  "detail": "Le champ 'montant' doit être un entier positif.",
  "status": 400,
  "instance": "/v1/payments"
}

L'endpoint de checkout actuellement déployé en sandbox utilise un format d'erreur simplifié, décrit sur sa page de référence. Les deux formats convergeront vers RFC 7807 à l'ouverture de la production.

Sandbox & clés de test

Le bac à sable reproduit le comportement de l'API sans mouvement de fonds réel. Aucune échéance d'abonnement n'y est prélevée automatiquement, et les transactions sont simulées.

Créez un compte pour générer vos clés sandbox et tester vos intégrations sans impact sur des flux réels.

Créer un compte Demander un accès sandbox

SDKs

Des SDKs officiels Djaba (PHP, Node.js) seront publiés au fur et à mesure de la disponibilité des API en production.

En attendant, pour la génération de QR codes interopérables, Djaba Marchand est compatible avec le SDK QR Code de l'écosystème PI-SPI — déjà disponible et maintenu par l'écosystème régional, dans 4 langages :

Langage	Installation
JavaScript	`npm install @pi-spi/qrcode`
Python	`pip install pi-spi-qrcode`
Flutter	`flutter pub add pi_spi_qrcode`
Java	`implementation 'io.pispi:qrcode'`

Fonctionnalités couvertes : création de payload EMV statique ou dynamique, décodage, validation de payloads existants et d'alias, génération de QR codes en SVG. Compatible avec les liens de paiement Djaba Marchand — un seul SDK pour tous vos participants PI-SPI.

import { createStaticPayload } from '@pi-spi/qrcode';

const qr = createStaticPayload({
  alias: 'DJABA-MARCHAND-4821',
  amount: 15000,
  currency: 'XOF'
});

Statut des services

La page de statut public listera la disponibilité en temps réel de l'API Connect, de l'API Marchand et de l'infrastructure d'interconnexion. Disponible à l'ouverture de la plateforme.