Démarrage

API v1.0

Stable

Documentation Zayono

Bienvenue. Cette documentation vous guide pas à pas pour intégrer Zayono dans votre business et commencer à accepter des paiements partout en Afrique via une seule API.

Documentation en construction Ce contenu est un aperçu de la documentation finale. Il sera enrichi progressivement.

Comment fonctionne l'API ?

L'API Zayono est simple : vous envoyez une requête pour créer une session de paiement, vous redirigez votre client vers l'URL générée, et Zayono prend en charge tout le reste : sélection du moyen de paiement, sécurité, et confirmation. Toutes les requêtes se font via HTTPS.

Base URL

https://api.zayono.com/v1

Démarrage rapide

Créez votre première session de paiement en 4 étapes.

Créez votre compte

Inscrivez-vous sur zayono.com pour accéder au dashboard et générer vos clés API.

Récupérez votre clé API

Dans le dashboard, allez dans Paramètres → Clés API pour obtenir votre clé secrète.

Créez une session de paiement

Envoyez une requête à l'API et redirigez votre client vers l'URL de paiement reçue en réponse.

Recevez la confirmation

Configurez un webhook sur votre serveur pour recevoir la confirmation de paiement en temps réel.

Exemple cURL

curl -X POST https://api.zayono.com/v1/sessions \
  -H "Authorization: Bearer sk_live_••••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "amount":     15000,
    "currency":   "XOF",
    "country":    "SN",
    "reference":  "COMMANDE-001",
    "return_url": "https://votre-site.com/merci"
  }'

Installation

Installez le SDK officiel Zayono pour votre langage.

Node.js

npm install @zayono/node

Python

pip install zayono

PHP

composer require zayono/php-sdk

Authentification

Clés API

Zayono utilise deux types de clés : les clés de test (préfixe sk_test_) et les clés de production (préfixe sk_live_). Utilisez les clés de test pendant le développement, elles ne génèrent pas de vrais paiements.

Ne partagez jamais vos clés secrètes Stockez-les dans des variables d'environnement et ne les incluez jamais dans votre code source.

En-têtes requis

Chaque requête à l'API doit inclure ces en-têtes.

En-tête	Valeur
Authorization	`Bearer sk_live_••••`	Requis
Content-Type	`application/json`	Requis
Idempotency-Key	`string`	Optionnel

API : Sessions

Créer une session

Une session représente une demande de paiement. Créez-en une, puis redirigez votre client vers l'URL reçue.

POST/v1/sessions

Crée une nouvelle session de paiement et retourne une URL de checkout.

Paramètres

Paramètre	Type		Description
amount	integer	Requis	Montant (ex : 15000 = 150,00 XOF).
currency	string	Requis	Code devise ISO 4217 : `XOF`, `GHS`, `KES`…
country	string	Requis	Code pays ISO 3166 : `SN`, `CI`, `KE`…
reference	string	Requis	Votre référence de commande unique.
return_url	string	Requis	URL de redirection après paiement réussi.
cancel_url	string	Optionnel	URL si le client annule le paiement.
customer	object	Optionnel	Infos client : `name`, `email`, `phone`.
metadata	object	Optionnel	Données libres retournées dans les webhooks.

Exemple

Node.js

const zayono = require('@zayono/node');
const client  = new zayono.Client('sk_live_••••••••••••••');

const session = await client.sessions.create({
  amount:     15000,
  currency:   'XOF',
  country:    'SN',
  reference:  'COMMANDE-001',
  return_url: 'https://votre-site.com/merci',
  customer:   { name: 'Adama Diallo', email: 'adama@exemple.com' }
});

// Redirigez le client →
redirect(session.checkout_url);

JSON : 201 Created

{
  "id":           "ses_01HXYZ123ABC",
  "status":       "pending",
  "amount":       15000,
  "currency":     "XOF",
  "checkout_url": "https://checkout.zayono.com/pay/ses_01HXYZ123ABC",
  "expires_at":   "2026-05-28T14:30:00Z"
}

Récupérer une session

GET/v1/sessions/{id}

Récupère les détails d'une session de paiement par son identifiant.

cURL

curl https://api.zayono.com/v1/sessions/ses_01HXYZ123ABC \
  -H "Authorization: Bearer sk_live_••••••••••••••"

Lister les sessions

GET/v1/sessions

Retourne la liste paginée de vos sessions. Paramètres optionnels : limit, after, status, country.

Webhooks

Présentation

Un webhook est une notification automatique envoyée par Zayono vers votre serveur lorsqu'un événement se produit (paiement réussi, échoué, remboursement…). Vous devez configurer une URL dans votre dashboard pour les recevoir.

Bonne pratiqueToujours confirmer un paiement via webhook, jamais seulement via la redirection return_url.

Vérification de signature

Chaque webhook est signé avec HMAC-SHA256. Vérifiez toujours la signature pour vous assurer que la requête vient bien de Zayono.

Node.js

const crypto = require('crypto');

app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const sig      = req.headers['x-zayono-signature'];
  const expected = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (sig !== expected) return res.sendStatus(401);

  const event = JSON.parse(req.body);
  // Traitez l'événement ici...
  res.sendStatus(200);
});

Événements disponibles

session.completed

Paiement confirmé avec succès.

session.failed

Tentative de paiement échouée.

session.expired

Session expirée sans paiement.

refund.created

Un remboursement a été initié.

refund.completed

Remboursement finalisé.

dispute.opened

Un litige a été ouvert.

SDKs

Bibliothèques officielles

Des SDKs maintenus par l'équipe Zayono pour les langages les plus utilisés.

Node.js

v1.2.0

npm install @zayono/node

Python

v1.1.3

pip install zayono

PHP

v1.0.8

composer require zayono/zayono-php

WooCommerce

v1.0.0

wordpress.org/plugins/zayono-woocommerce

Laravel

Bientôt

—

Référence

Codes d'erreur

En cas d'erreur, l'API retourne un objet JSON avec le détail du problème.

JSON

{ "error": { "code": "invalid_amount", "message": "Le montant doit être supérieur à 100.", "status": 422 } }

HTTP	Code	Description
400	bad_request	Requête mal formée.
401	unauthorized	Clé API invalide ou manquante.
404	not_found	Ressource introuvable.
409	duplicate_reference	Référence de commande déjà utilisée.
422	invalid_amount	Montant invalide ou trop faible.
429	rate_limit	Trop de requêtes, réessayez plus tard.
500	server_error	Erreur interne. Contactez le support.

Changelog

2026-05-01

v1.0.0 : Stable

Lancement officiel de l'API Zayono v1.
Sessions de paiement, webhooks HMAC, SDKs Node/Python/PHP.
18 agrégateurs disponibles : PawaPay, FedaPay, FeexPay, KKiaPay, iPay Money, PayDunya, Hub2 (7 pays), PAL Africa, Paystack, PayTech, PayPlus, Cryptomus, Qosic, Notch Pay, Magma OnePay, Coinbase Commerce, Stripe, Flutterwave.

2026-03-15

v0.9.0 : Beta

Programme bêta fermé, accès sur invitation.
API de sessions et routage intelligent par pays.

Intégrations Commencer gratuitement