WOLYPAY — Documentation API partenaire

Prise en main

L'API expose les services de paiement de WOLYPAY : achat d'énergie, transfert international, mobile money et réabonnement télévision. Toutes les requêtes passent par https://sandbox.wolypay.com/api/v1, en HTTPS.

Une opération suit toujours la même forme : vous la créez, elle passe par une ou plusieurs étapes de confirmation, puis elle se clôt. C'est à la clôture — et seulement là — que votre serveur est notifié.

Cette page couvre ce qu'il faut savoir avant d'écrire la première requête. Le détail de chaque paramètre et de chaque réponse est dans la référence complète.

Authentification

Vos identifiants vous sont remis par le support. Ils s'échangent contre un jeton, à présenter ensuite sur chaque appel.

Obtenir un jeton

POST https://sandbox.wolypay.com/api/v1/provider/login
Content-Type: application/json

{
    "api_key":  "votre_api_key",
    "pass_key": "votre_pass_key"
}

Présenter le jeton

Authorization: Bearer <votre_jeton>
Accept: application/json

GET /provider/account rend l'état de votre compte et son solde. C'est aussi la façon la plus simple de vérifier qu'un jeton est encore valable.

Services

Chaque service a son préfixe. Les opérations et leurs paramètres sont décrits dans la référence — cette page ne les recopie pas, une liste tenue à la main finissant toujours par mentir.

Service	Préfixe	Notifications
Achat Énergie — prépayé	/provider/prepaid	oui — `prepaid`
Achat Énergie — postpayé	/provider/postpaid	oui — `postpaid`
WelyFX — paiement	/provider/welyfx	oui — `welyfx`
WelyFX — envoi	/provider/welyfx/send	oui — `welyfx`
Orange Money	/provider/orange-money	oui — `orange-money`
MTN Mobile Money	/provider/mtn-momo	oui — `mtn-momo`
CANAL+	/provider/canal	oui — `canal`

Un service marqué « non » fonctionne normalement : seule la notification sortante n'existe pas encore pour lui. Interrogez alors l'opération pour connaître son issue.

Notifications

Quand une opération se clôt, WOLYPAY envoie une requête à votre serveur, sur l'URL que vous avez fait déclarer pour le service. Elle part une fois l'issue acquise — jamais avant, jamais sur un état intermédiaire.

Cette requête n'est pas un endpoint de notre API : c'est nous qui appelons votre URL. Rien de ce qui suit ne s'appelle depuis un client généré.

Ce que vous recevez

POST https://votre-domaine/votre-url-de-reception
X-Wolypay-Signature: <hmac-sha256 hexadécimal minuscule>
X-Wolypay-Timestamp: 1787241489
X-Wolypay-Service:   canal
X-Wolypay-Event:     operation.completed
X-Wolypay-Delivery:  <uuid de la tentative>

{
    "event":     "operation.completed",
    "service":   "canal",
    "reference": "b1e1f0aa-0000-4000-8000-000000000001",
    "sent_at":   "2026-08-22T13:38:09+00:00",
    "data":      { ... }
}

Vérifier la signature

Calculez un HMAC-SHA256 sur la chaîne horodatage.corps-brut — un point entre les deux — avec pour clé le secret du service concerné. Comparez le résultat, en hexadécimal minuscule, à X-Wolypay-Signature, avec une comparaison à temps constant.

Signez le corps tel qu'il arrive. Le re-sérialiser, ne serait-ce qu'en réordonnant ses clés, produit une signature différente.
Rejetez tout horodatage vieux de plus de 300 secondes. C'est ce qui empêche de rejouer une notification interceptée.
Choisir le bon secret. Si vous avez fait déclarer la même URL pour plusieurs services, lisez X-Wolypay-Service avant de vérifier. Cet en-tête n'est pas signé et ne fait pas foi : il vous dit seulement quelle clé essayer sans avoir à lire un corps que vous n'avez pas encore authentifié. Le champ service du corps, lui, est signé.

Dédoublonner

La remise est « au moins une fois ». Dédoublonnez sur reference, jamais sur X-Wolypay-Delivery qui identifie la tentative et change à chaque réessai. Sans cela, un client sera crédité deux fois.

Réessais

Toute réponse hors 2xx, et tout délai dépassé, relance la remise à 1 min, 5 min, 15 min, 1 h puis 6 h.

Répondez 200 dès la prise en charge, sans attendre d'avoir traité : un traitement long provoque un délai dépassé, donc un réessai, donc un doublon.

Les redirections ne sont pas suivies — votre URL doit répondre directement, en HTTPS. Les tentatives se consultent par GET /provider/webhooks/deliveries/{reference}.

Déclarer une URL

Une destination par service, à faire déclarer par le support. GET /provider/webhooks vous rend celles qui sont en place.

Référence complète

Chaque opération, ses paramètres, ses réponses et ses codes d'erreur sont décrits dans la documentation interactive.

Ouvrir la référence