Checkout intégré

Déployé en sandbox. C'est aujourd'hui le seul endpoint Djaba appelable programmatiquement.

Principe

Le checkout se déroule en deux temps. Votre serveur crée une session avec votre clé secrète, ce qui fixe le montant et le libellé — le client ne peut donc pas les altérer. Votre page ouvre ensuite cette session dans une fenêtre modale, en ne manipulant que l'identifiant de session.

Votre serveur appelle POST /api/v1/checkout/sessions et reçoit un id de session.
Votre page charge djaba-checkout.js et appelle DjabaCheckout.open() avec cet id.
Le client paie dans la fenêtre modale ; votre callback onSuccess reçoit la référence de transaction.

Créer une session

POST /api/v1/checkout/sessions

Appel serveur à serveur, authentifié par votre clé secrète sandbox. Cet endpoint est exempté de la protection CSRF appliquée au reste du site : il s'authentifie uniquement par la clé API.

Paramètres du corps (JSON)

Champ	Type	Requis	Description
`amount`	number	Oui	Montant à encaisser, strictement positif. En unité entière de la devise (`15000` = 15 000 XOF).
`currency`	string	Non	Code devise. Défaut : `XOF`.
`label`	string	Non	Libellé présenté au payeur. Défaut : `Paiement Djaba`.
`return_url`	string	Non	URL de redirection après paiement. Défaut : aucune.

Requête

curl -X POST https://djaba.io/api/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 15000,
    "currency": "XOF",
    "label": "Commande #4821",
    "return_url": "https://votre-site.com/merci"
  }'

Réponse — `201 Created`

{
  "id": "cs_9f2b7c1e4a8d0356b1e2f4a7",
  "amount": 15000,
  "currency": "XOF",
  "status": "pending",
  "checkout_url": "/checkout/cs_9f2b7c1e4a8d0356b1e2f4a7",
  "expires_at": "2026-08-17 14:32:10"
}

Champ	Type	Description
`id`	string	Identifiant de session : préfixe `cs_` suivi de 24 caractères hexadécimaux.
`amount`	number	Montant enregistré pour la session.
`currency`	string	Devise de la session.
`status`	string	`pending` à la création, `completed` après paiement.
`checkout_url`	string	Page de paiement hébergée. C'est l'URL chargée par le widget.
`expires_at`	string	Expiration de la session, 30 minutes après sa création.

Ouvrir le paiement côté client

Le widget n'a besoin que de l'identifiant de session. Aucune clé secrète ne transite par le navigateur.

<script src="https://djaba.io/assets/js/djaba-checkout.js"></script>
<button id="payer">Payer</button>

<script>
  document.getElementById('payer').addEventListener('click', function () {
    DjabaCheckout.open({
      sessionId: 'cs_9f2b7c1e4a8d0356b1e2f4a7',
      onSuccess: function (result) {
        console.log('Payé !', result.reference);
      }
    });
  });
</script>

La page de checkout est volontairement autorisée à être embarquée dans une iframe tierce — contrairement au reste du site, protégé contre le clickjacking.

Erreurs

Les erreurs de cet endpoint suivent un format simplifié, distinct du format RFC 7807 visé pour la production :

{
  "error": {
    "type": "invalid_request",
    "message": "Le champ 'amount' doit être un nombre positif."
  }
}

Code	Type	Cause
`401`	`authentication_error`	Clé absente, mal formée, révoquée ou inconnue. Seules les clés `sk_test_` sont acceptées.
`400`	`invalid_request`	`amount` manquant, nul ou négatif.

Tester sans écrire de code

Votre espace marchand permet de créer une session de test et de dérouler le parcours complet dans les mêmes conditions que vos clients.

Tester le checkout Générer une clé sandbox