Cette API vous permet d'encaisser par Orange Money, Wave, Free Money, carte bancaire et plusieurs autres moyens de paiement, avec un seul contrat et une seule intégration.
URL de base : https://paygate-api.clarizegroup.com
Toutes les requêtes et réponses sont en JSON. Les montants sont des entiers en FCFA (XOF).
1. Vos identifiants
Vous avez reçu :
| Valeur | Exemple | Usage |
|---|---|---|
APP_ID |
app_test_0a2272… |
Identifie votre application |
APP_SECRET |
sk_test_… |
Authentifie vos appels — à garder secret |
WEBHOOK_SECRET |
whsec_… |
Vérifie les notifications que nous vous envoyons |
Les identifiants app_test_ / sk_test_ utilisent notre bac à sable (aucun argent réel). Pour la production, vous recevrez une paire app_live_ / sk_live_ et un WEBHOOK_SECRET live différent de celui du test.
Sur votre serveur de production, configurez uniquement le
WEBHOOK_SECRETlive. Ainsi, une notification issue d'un paiement de test (argent fictif) sera automatiquement rejetée par votre vérification de signature.
Attention : Appelez l'API uniquement depuis votre serveur. Ne mettez jamais
APP_SECRETdans une application mobile ou du JavaScript côté navigateur.
2. Authentification
Ajoutez deux en-têtes à chaque requête :
X-App-Id: <APP_ID>
X-App-Secret: <APP_SECRET>
(L'authentification HTTP Basic APP_ID:APP_SECRET est aussi acceptée.)
Test rapide :
curl https://paygate-api.clarizegroup.com/v1 -H "X-App-Id: $APP_ID" -H "X-App-Secret: $APP_SECRET"
3. Le parcours de paiement
- Votre serveur crée un paiement → vous recevez un
checkout_url. - Vous redirigez le client vers
checkout_url(notre page de paiement). - Le client paie. Il est renvoyé vers votre
return_url(oucancel_urls'il annule). - Nous vous envoyons un webhook
payment.completedsur votre serveur. - Vous livrez la commande à réception du webhook (ou après avoir vérifié le statut via
GET /v1/payments/:id).
Ne validez jamais une commande sur la simple arrivée du client sur
return_url: cette page peut être ouverte sans paiement.
4. Créer un paiement
POST /v1/payments
curl -X POST https://paygate-api.clarizegroup.com/v1/payments \
-H "X-App-Id: $APP_ID" -H "X-App-Secret: $APP_SECRET" \
-H "Content-Type: application/json" \
-d '{
"amount": 15000,
"description": "Commande #1001",
"reference": "CMD-1001",
"customer": { "name": "Moussa Diop", "phone": "771234567", "email": "moussa@exemple.sn" },
"items": [ { "name": "Montre", "quantity": 2, "unit_price": 7500 } ],
"return_url": "https://maboutique.sn/paiement/merci",
"cancel_url": "https://maboutique.sn/panier",
"notify_url": "https://maboutique.sn/api/paygate/webhook",
"metadata": { "order_id": 1001 }
}'
| Champ | Obligatoire | Description |
|---|---|---|
amount |
oui | Montant total en FCFA (entier > 0) |
description |
oui | Affichée sur la page de paiement (255 car. max) |
reference |
oui | Votre identifiant de commande, unique. Voir Idempotence |
customer |
non | name, phone, email — préremplissent la page de paiement |
items |
non | Lignes affichées au client (name, quantity, unit_price, description) |
channels |
non | Restreint les moyens de paiement, ex. ["orange-money-senegal", "card"] (liste des canaux : section 4 bis, GET /v1/payment-options) |
return_url |
non | Redirection après paiement réussi (https:// obligatoire) |
cancel_url |
non | Redirection si le client annule (https:// obligatoire) |
notify_url |
non | URL de votre serveur qui recevra le webhook de ce paiement (https://, adresse publique). Sinon, l'URL webhook par défaut de votre compte est utilisée |
metadata |
non | Données libres, renvoyées telles quelles |
Nous ajoutons payment_id et reference en paramètres à return_url et cancel_url, par ex. https://maboutique.sn/paiement/merci?payment_id=pay_8f3…&reference=CMD-1001 (un paramètre technique token peut aussi être présent).
Réponse 201 Created :
{
"id": "pay_8f3a1c9e2b7d4a6f0e1c2b3a",
"object": "payment",
"mode": "test",
"reference": "CMD-1001",
"amount": 15000,
"currency": "XOF",
"fee": 300,
"fee_details": { "processing": 300, "commission": 0 },
"net_amount": 14700,
"description": "Commande #1001",
"status": "pending",
"checkout_url": "https://paygate-api.clarizegroup.com/pay/pay_8f3a…",
"payment_token": "test_XXXX",
"customer": {
"name": "Moussa Diop",
"phone": "771234567",
"email": "moussa@exemple.sn"
},
"items": [{ "name": "Montre", "quantity": 2, "unit_price": 7500 }],
"metadata": { "order_id": 1001 },
"receipt_url": null,
"fail_reason": null,
"failure": null,
"paid_at": null,
"created_at": "2026-10-18T18:02:11.412Z",
"updated_at": "2026-10-18T18:02:11.902Z"
}
Redirigez ensuite le client vers checkout_url.
Frais
Le client paie exactement amount. Les frais d'encaissement (fee) sont de 2 % du montant, arrondis au FCFA, et couvrent les frais de l'opérateur de paiement et la TTF. Ils sont retenus sur votre solde : net_amount = amount − fee, crédité dès que le paiement est completed.
Idempotence
reference est unique par compte et par mode. Si vous renvoyez la même reference avec le même montant (par ex. après un timeout réseau), vous recevez le même paiement (200 OK) — aucun doublon n'est créé. Avec un autre montant : erreur 409 reference_conflict.
Si la création de facture est encore en cours ou si sa réponse fournisseur a été perdue, le retry retourne 409 payment_initialization_uncertain avec le payment_id conservé. Ne changez pas de référence pour contourner cette erreur : le support doit rapprocher la facture existante. Le champ initialization_state vaut initializing, ready ou reconciliation_required. Un paiement reste pending tant que l'encaissement n'est pas confirmé ; cet état ne garantit pas qu'un lien de paiement est déjà disponible.
4 bis. Paiement direct en un seul appel
POST /v1/payments/:country/:payment_option
Cet appel crée le paiement et sa facture, puis demande le lien de l'opérateur sélectionné. Vous n'avez pas besoin d'un ID de paiement au préalable. Utilisez les mêmes en-têtes d'authentification que pour POST /v1/payments.
Exemple : Wave Sénégal
curl -X POST "https://paygate-api.clarizegroup.com/v1/payments/SN/wave" \
-H "X-App-Id: $APP_ID" -H "X-App-Secret: $APP_SECRET" \
-H "Content-Type: application/json" \
-d '{
"amount": 15000,
"reference": "CMD-1001",
"description": "Commande #1001",
"customer": {
"name": "Moussa Diop",
"email": "moussa@exemple.sn",
"phone": "+221771234567"
},
"notify_url": "https://maboutique.sn/api/paygate/webhook"
}'
Le corps accepte les champs de création de paiement de la section 4. amount, reference, description et les trois champs customer.name, customer.email, customer.phone sont obligatoires pour ce parcours. country et payment_option se trouvent dans l'URL ; ne les dupliquez pas dans le corps. L'API sélectionne le canal correspondant. Si vous fournissez channels, la liste doit autoriser ce canal.
La réponse est l'objet paiement habituel enrichi de next_action (201 pour un nouveau paiement, 200 pour une référence existante). Extrait :
{
"id": "pay_EXEMPLE",
"reference": "CMD-1001",
"amount": 15000,
"currency": "XOF",
"status": "pending",
"next_action": {
"type": "redirect",
"country": "SN",
"payment_option": "wave",
"operator": "wave-senegal",
"url": "https://pay.wave.com/c/EXEMPLE",
"links": {}
}
}
Ouvrez next_action.url pour que le client autorise le paiement. L'id est généré par l'API : conservez-le pour GET /v1/payments/:id et pour le rapprochement avec les webhooks. Obtenir un lien ne signifie pas que le paiement est effectué : attendez payment.completed ou vérifiez le statut avant de livrer.
Pays et options pris en charge
country est un code ISO à deux lettres ; les pays et options dans l'URL acceptent indifféremment les majuscules et minuscules.
| Pays | Option | Route en un appel | Téléphone national |
|---|---|---|---|
Sénégal (SN) |
Wave | POST /v1/payments/SN/wave |
9 chiffres commençant par 7, ex. 771234567 |
Sénégal (SN) |
Orange Money | POST /v1/payments/SN/orange-money |
Même format |
Côte d'Ivoire (CI) |
Wave | POST /v1/payments/CI/wave |
10 chiffres commençant par 0, ex. 0701234567 |
Les préfixes internationaux 221 / +221 et 225 / +225 sont acceptés pour leur pays respectif. Les zéros initiaux sont conservés. Une combinaison non implémentée est refusée avant la création de facture ; par exemple, CI/orange-money n'est pas prise en charge par cette intégration.
Pour Orange Money Sénégal, next_action.url ouvre une page QR dédiée à cet opérateur. Les liens facultatifs next_action.links.orange_money et next_action.links.maxit ouvrent l'application correspondante sur mobile. Ces parcours évitent le sélecteur multi-opérateurs ; ils ne garantissent pas un push automatique sur le téléphone.
Découvrir les options pour une interface dynamique
GET /v1/payment-options
GET /v1/payment-options/SN
Ces routes nécessitent vos identifiants marchands. La première liste toutes les options implémentées ; la seconde filtre par pays (422 unsupported_country pour un pays inconnu). Réponse au format {"object":"list","data":[...]} ; exemple d'une entrée :
{
"country": "SN",
"country_name": "Sénégal",
"payment_option": "wave",
"name": "Wave",
"operator": "wave-senegal",
"currency": "XOF",
"flow": "redirect",
"modes": ["live"],
"mode_supported": true,
"phone": { "calling_code": "221", "national_example": "771234567" }
}
Utilisez country et payment_option pour construire l'URL de création, et name pour le libellé de votre bouton. mode_supported indique si ce parcours existe dans le mode de votre clé (actuellement false en test). Ce catalogue décrit les capacités de l'intégration ; il ne garantit pas la disponibilité instantanée de chaque opérateur.
Réessais et erreurs
Conservez la même reference et le même montant en cas de nouvelle tentative. Une même référence retrouve le même paiement ; une initiation déjà réussie renvoie son lien sans nouvelle initiation. Un paiement déjà completed est renvoyé avec next_action: null.
Si la facture existe mais que l'initiation échoue, l'erreur contient error.details.payment_id et error.details.reference. Vérifiez ce paiement avant toute reprise. Une initiation en cours ou dont le résultat est incertain reste réservée (409 softpay_in_progress) pour éviter les doubles initiations. Ne changez pas automatiquement de référence pour contourner ce verrou. Un autre client ou opérateur ne peut pas réutiliser une initiation existante (409 softpay_conflict ou 422 operator_not_allowed si le canal est exclu).
Autres erreurs : 409 reference_conflict (montant différent), 409 payment_not_ready, 409 payment_not_pending, 422 validation_error (dont pays / option / téléphone invalide), 502 provider_rejected, 502 provider_unreachable, 502 provider_bad_response, 502 provider_http_error, 503 mode_not_configured.
Mode live uniquement : 422 softpay_live_only en test, avant création du paiement. Utilisez le checkout hébergé pour les tests marchands. La disponibilité de chaque opérateur en live vous est confirmée à l'ouverture de votre compte.
Compatibilité : paiement déjà créé
Si votre application dispose déjà d'un paiement, elle peut continuer à utiliser :
POST /v1/payments/:id/softpay/SN/wave
Le corps contient uniquement {"customer":{"name":"Moussa Diop","email":"moussa@exemple.sn","phone":"771234567"}}. Ici :id désigne l'ID du paiement existant. La réponse reste {"payment_id":"pay_…","next_action":{...}}.
L'ancienne route POST /v1/payments/:id/softpay accepte toujours {"operator":"wave-senegal","customer":{...}}. Elle accepte aussi {"country":"SN","payment_option":"wave","customer":{...}}. Les trois formes partagent la même réservation et le même lien. Un ID absent ou appartenant à un autre marchand / mode renvoie 404 payment_not_found.
GET /v1/payments/:id et les listes exposent next_action pour les paiements en attente (null pour les statuts finaux). Le checkout_url historique reste disponible ; présentez au client le parcours que vous avez choisi.
5. Statuts
status |
Signification |
|---|---|
pending |
En attente de paiement |
completed |
Payé : vous pouvez livrer. Statut définitif |
cancelled |
Annulé par le client, ou expiré (facture non payée sous 24 h) |
failed |
Échec du paiement (voir failure) |
Comprendre un échec : l'objet failure
Pour un paiement cancelled ou failed, le champ failure (dans l'objet paiement et dans les webhooks payment.cancelled / payment.failed) indique l'origine de l'échec. Il vaut null pour les autres statuts.
"failure": {
"category": "customer",
"code": "customer_abandoned",
"message": "The customer cancelled, did not confirm the payment on their wallet, or let the checkout expire."
}
category |
code |
Signification |
|---|---|---|
customer |
customer_abandoned |
Le client a annulé, n'a pas validé sur son téléphone, ou a laissé expirer le paiement |
technical |
amount_mismatch |
Montant confirmé différent du montant demandé |
technical |
provider_error |
Erreur technique chez le fournisseur de paiement |
message est un texte lisible (en anglais) que vous pouvez afficher. Basez votre logique sur category et code, qui sont stables ; de nouveaux codes pourront s'ajouter. fail_reason reste disponible pour compatibilité.
6. Consulter un paiement
GET /v1/payments/{id} — si le paiement est encore pending, nous vérifions son statut en temps réel avant de répondre.
GET /v1/payments?status=completed&limit=20 — liste du plus récent au plus ancien.
Filtres : status, reference, limit (1–100). Pagination : has_more + starting_after=<id du dernier élément>.
Retrouver un paiement par votre référence : GET /v1/payments?reference=CMD-1001.
Plafond journalier
En production, votre compte peut avoir un plafond d'encaissement par jour (journée calendaire, heure de Dakar). Les paiements en attente réservent leur montant ; s'ils sont annulés ou échouent, il est libéré. Au-delà, la création renvoie 403 daily_limit_exceeded avec details.remaining_today.
GET /v1/limits :
{
"object": "limits",
"daily_limit": 10000000,
"used_today": 2350000,
"remaining_today": 7650000,
"currency": "XOF",
"applies_to": "live"
}
Votre solde
GET /v1/balance — montant disponible (paiements nets encaissés, moins les payouts effectués ou en cours) :
{
"object": "balance",
"mode": "live",
"available": 147000,
"reserved_for_payouts": 25000,
"payouts_in_progress": 1,
"currency": "XOF"
}
GET /v1/balance/transactions — historique des mouvements, du plus récent au plus ancien (payment = crédit d'un paiement, payout = débit d'un payout, payout_reversal = recrédit d'un payout refusé ou échoué, adjustment = correction). Pagination : limit, has_more, starting_after=<id>.
7. Payouts (transferts sortants)
Envoyez de l'argent depuis votre solde vers un compte mobile money (Wave, Orange Money, Free Money…). Le service doit être activé sur votre compte.
Frais : 1,8 % TTC du montant envoyé, arrondis au FCFA, débités de votre solde en plus du montant (total_debited = amount + fee). Le bénéficiaire reçoit exactement amount. En cas de refus ou d'échec, le montant et les frais sont recrédités.
Parcours :
- Vous créez le payout → le montant est immédiatement réservé sur votre solde ; statut
pending_approval. - Notre équipe le valide (contrôle anti-fraude), puis le transfert est exécuté →
processingpuiscompleted. - S'il est refusé (
rejected) ou échoue chez l'opérateur (failed), le montant est recrédité sur votre solde. - Vous recevez un webhook
payout.completed,payout.failedoupayout.rejected.
Mode automatique (sur activation explicite du compte) : le même POST /v1/payouts
réserve le montant et les frais, puis lance le transfert sans validation manuelle.
Il peut répondre processing ou completed ; auto_approved précise le mode choisi.
Cela ne garantit pas une réception instantanée chez l'opérateur. Seul completed
confirme le transfert ; un webhook en retard ne justifie pas une nouvelle demande.
Le montant envoyé plus les frais de payout doit être couvert par les
encaissements nets confirmés et non déjà dépensés/réservés. Les encaissements en
attente et les ajustements positifs ne financent pas ce mode. Des plafonds par
opération/jour et une liste de moyens autorisés sont appliqués au compte.
Le plafond journalier est calculé en UTC, frais inclus. GET /v1/balance expose
payin_funded_available et automatic_payouts_active en complément du solde habituel.
Retries : réutilisez toujours la même reference après un timeout. La référence
identifie durablement un payout par compte et mode. Changer son montant, bénéficiaire
ou moyen est refusé (HTTP 409). Les callbacks et métadonnées initiaux sont conservés.
Ne créez pas une nouvelle référence pour contourner un statut processing.
Une erreur réseau ou un résultat incertain conserve le montant réservé jusqu'au
rapprochement ; aucun recrédit ne vaut confirmation de réception chez le bénéficiaire.
Erreurs du mode automatique : 503 automatic_payouts_paused,
403 payout_method_not_allowed, 409 payout_amount_limit_exceeded,
409 payout_daily_limit_exceeded, 409 insufficient_payin_balance.
POST /v1/payouts
curl -X POST https://paygate-api.clarizegroup.com/v1/payouts \
-H "X-App-Id: $APP_ID" -H "X-App-Secret: $APP_SECRET" \
-H "Content-Type: application/json" \
-d '{
"amount": 25000,
"account_alias": "771234567",
"withdraw_mode": "wave-senegal",
"reference": "PAYOUT-2001",
"description": "Paiement fournisseur",
"notify_url": "https://maboutique.sn/api/paygate/webhook",
"metadata": { "supplier_id": 42 }
}'
| Champ | Obligatoire | Description |
|---|---|---|
amount |
oui | Montant en FCFA (entier, minimum 100) |
account_alias |
oui | Numéro du bénéficiaire sans indicatif pays (ex. 771234567) |
withdraw_mode |
oui | Opérateur : wave-senegal, orange-money-senegal, free-money-senegal, expresso-senegal, djamo-sn, wave-ci, orange-money-ci, mtn-ci, moov-ci, djamo-ci, mtn-benin, moov-benin, celtiis-cash, t-money-togo, moov-togo, orange-money-mali, orange-money-burkina, moov-burkina-faso, mtn-cameroun (liste : GET /v1/payouts/methods) |
reference |
oui | Votre identifiant unique (idempotence : même référence = même payout) |
description |
non | Libellé interne |
notify_url |
non | URL https:// qui recevra le webhook de ce payout |
metadata |
non | Données libres, renvoyées telles quelles |
Réponse 201 Created :
{
"id": "po_3f1a9c2b7d4e6f8a0b1c2d3e",
"object": "payout",
"mode": "live",
"reference": "PAYOUT-2001",
"amount": 25000,
"fee": 450,
"total_debited": 25450,
"currency": "XOF",
"account_alias": "771234567",
"withdraw_mode": "wave-senegal",
"status": "pending_approval",
"transaction_id": null,
"provider_ref": null,
"fail_reason": null,
"notify_url": "https://maboutique.sn/api/paygate/webhook",
"metadata": { "supplier_id": 42, "description": "Paiement fournisseur" },
"reviewed_at": null,
"completed_at": null,
"created_at": "2026-10-21T15:30:42.351Z",
"updated_at": "2026-10-21T15:30:42.351Z"
}
status |
Signification |
|---|---|
pending_approval |
En attente de validation ; montant réservé |
processing |
Réservé, en attente de transmission, en cours ou en rapprochement ; réception non confirmée |
completed |
Transfert effectué (transaction_id, provider_ref renseignés). Définitif |
failed |
Échec chez l'opérateur — montant recrédité |
rejected |
Refusé par notre équipe (fail_reason précise le motif) — montant recrédité |
Consulter : GET /v1/payouts/{id} · Lister : GET /v1/payouts?status=completed&limit=20 (filtres status, reference, pagination starting_after).
Erreurs spécifiques : 403 payouts_disabled (service non activé), 409 insufficient_balance (details.balance, details.required), 409 reference_conflict (référence déjà utilisée pour un autre payout), 422 validation_error.
En mode test, les payouts sont simulés après validation (aucun argent ne part) : idéal pour intégrer le parcours et les webhooks.
7 bis. Abonnements (paiements récurrents)
Facturez un client chaque semaine ou chaque mois. Avec le mobile money, aucun prélèvement ne se fait sans le client : à chaque échéance, nous créons une demande de paiement (un paiement ordinaire, avec son checkout_url) que le client doit valider. Nous relançons automatiquement en cas d'impayé.
Calendrier d'une échéance
| Moment | Ce qui se passe |
|---|---|
| J0 (date d'échéance) | 1re demande de paiement → webhook subscription.payment_requested |
| J+2 | Relance 1 si toujours impayée (nouvelle demande, nouveau lien) |
| J+5 | Relance 2 |
| J+8 | Suspension de l'abonnement → webhook subscription.suspended |
Dès qu'un paiement d'une échéance est confirmé, l'échéance est réglée, la période avance et vous recevez subscription.activated (première échéance) ou subscription.renewed. Les relances restantes sont annulées. Le traitement tourne chaque minute : comptez une à deux minutes entre la confirmation du paiement et le webhook d'abonnement.
Transmettez le lien au client. Chaque
subscription.payment_requestedcontientdata.latest_invoice.checkout_url. Envoyez-le par SMS, WhatsApp ou e-mail : c'est ce lien qui permet au client de payer. Si le client paie un ancien lien de la même échéance, le paiement est bien pris en compte.
Créer une offre
POST /v1/plans
| Champ | Type | Requis | Description |
|---|---|---|---|
name |
string | oui | Nom affiché (ex. « Standard ») |
amount |
int | oui | Montant par période, en FCFA |
interval |
string | oui | week ou month (même jour chaque mois, ramené au dernier jour si besoin) |
trial_days |
int | Essai gratuit de 0 à 90 jours : aucune demande avant la fin de l'essai |
curl -X POST https://paygate-api.clarizegroup.com/v1/plans \
-H "X-App-Id: $APP_ID" -H "X-App-Secret: $APP_SECRET" \
-H "Content-Type: application/json" \
-d '{"name": "Standard", "amount": 5000, "interval": "month"}'
{ "id": "plan_3a91…", "object": "plan", "mode": "test", "name": "Standard", "amount": 5000, "currency": "XOF",
"interval": "month", "trial_days": 0, "status": "active", "created_at": "2026-11-15T09:00:00.000Z" }
Autres routes : GET /v1/plans, GET /v1/plans/{id}, POST /v1/plans/{id}/archive (les abonnés existants continuent ; l'offre ne peut plus être choisie).
Abonner un client
POST /v1/subscriptions
| Champ | Type | Requis | Description |
|---|---|---|---|
plan |
string | oui | Identifiant de l'offre (plan_…) |
customer.phone |
string | oui | Numéro du client, ex. +221770000000 |
customer.name |
string | Nom du client | |
operator |
string | wave-senegal, orange-money-senegal ou free-money-senegal ; sinon le client choisit sur la page de paiement |
|
reference |
string | Votre identifiant client/contrat. Idempotence : renvoyer la même référence retourne l'abonnement existant (200) au lieu d'en créer un second |
|
notify_url |
string | URL HTTPS des webhooks de cet abonnement (sinon votre URL par défaut) | |
metadata |
object | Données libres, renvoyées telles quelles |
Sans essai gratuit, la première demande de paiement part immédiatement et son lien est dans la réponse :
{
"id": "sub_7c20…",
"object": "subscription",
"mode": "test",
"plan": "plan_3a91…",
"reference": "client-001",
"customer": { "phone": "77***4567", "name": "Client Démo" },
"operator": null,
"status": "incomplete",
"current_period_start": "2026-11-15T09:00:00.000Z",
"current_period_end": "2026-12-15T09:00:00.000Z",
"latest_invoice": {
"id": "sinv_51be…",
"object": "subscription_invoice",
"amount": 5000,
"status": "pending",
"attempts": 1,
"next_attempt_at": "2026-11-17T09:00:00.000Z",
"checkout_url": "https://…"
},
"…": "…"
}
Le numéro du client n'est jamais renvoyé en clair.
Statuts d'un abonnement
| Statut | Signification |
|---|---|
incomplete |
Abonnement créé, première échéance pas encore payée |
trialing |
Essai gratuit en cours |
active |
À jour |
past_due |
Échéance ouverte et impayée (relances en cours) |
paused |
En pause : aucune demande jusqu'à la reprise |
suspended |
3 demandes sans paiement : plus de demandes. Un paiement tardif de l'échéance, ou resume, le réactive |
canceled |
Annulé, définitif |
Gérer un abonnement
| Route | Effet |
|---|---|
GET /v1/subscriptions |
Liste (?status=, ?plan=, ?limit= jusqu'à 100, ?offset=) |
GET /v1/subscriptions/{id} |
Détail avec latest_invoice |
GET /v1/subscriptions/{id}/invoices |
Échéances (statut pending, paid, failed ou void) |
POST /v1/subscriptions/{id}/pause |
Pause ; corps facultatif {"resume_at": "2026-12-01T08:00:00Z"} pour une reprise automatique. L'échéance ouverte est annulée |
POST /v1/subscriptions/{id}/resume |
Reprise d'un abonnement en pause ou suspendu : nouvelle période à partir d'aujourd'hui, demande de paiement immédiate |
POST /v1/subscriptions/{id}/cancel |
Annulation immédiate ; corps facultatif {"reason": "…"} |
Paiements d'abonnement
Chaque demande est un paiement normal : il apparaît dans GET /v1/payments, déclenche les webhooks payment.* et crédite votre solde comme les autres. Sa reference vaut {id de l'échéance}-{n° de tentative} (ex. sinv_51be…-2) et son metadata contient subscription, subscription_invoice et attempt.
Webhooks d'abonnement
subscription.created, subscription.payment_requested, subscription.activated, subscription.renewed, subscription.past_due, subscription.suspended, subscription.paused, subscription.resumed, subscription.canceled. data contient l'objet abonnement (avec latest_invoice quand c'est utile). Signature et réessais : identiques aux autres webhooks (section 8).
7 ter. Liens de paiement, tarifs et personnalisation (dashboard)
Sans écrire de code, depuis votre dashboard :
- Liens de paiement : créez un lien (montant fixe ou libre, minimum et maximum, nombre de paiements, date d'expiration) et partagez-le par WhatsApp, SMS ou e-mail. Le client paie sur notre page ; chaque paiement apparaît dans vos paiements et déclenche les webhooks habituels. Son
metadata.payment_linkcontient l'identifiant du lien (plink_…). - Page de paiement : nom affiché, logo, site web, téléphone, couleur et mention en bas de page.
- Tarifs et plafonds : vos frais d'encaissement, votre commission, vos frais de payout, vos plafonds et délais. Vous pouvez y demander une révision de vos taux ; la réponse et la date d'effet des nouveaux taux s'affichent au même endroit. Les paiements déjà créés gardent leurs frais.
8. Webhooks
Quand un paiement change de statut, nous envoyons un POST JSON sur le notify_url du paiement, ou à défaut sur l'URL webhook par défaut de votre compte. Nous ne transmettons le statut qu'après l'avoir confirmé auprès de l'opérateur.
Événements : payment.completed, payment.cancelled, payment.failed, payout.completed, payout.failed, payout.rejected (data contient alors l'objet payout), et les événements subscription.* (section 7 bis)
{
"id": "evt_42",
"type": "payment.completed",
"created_at": "2026-10-18T18:03:40.120Z",
"data": {
"id": "pay_8f3a…",
"reference": "CMD-1001",
"amount": 15000,
"status": "completed",
"receipt_url": "https://…pdf",
"metadata": { "order_id": 1001 },
"…": "…"
}
}
En-têtes :
PayGate-Event-Id: evt_42
PayGate-Event-Type: payment.completed
PayGate-Signature: t=1760810620,v1=5f2c…
Répondez 200 rapidement. Toute autre réponse (ou un délai > 10 s) déclenche des réessais : après 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h. Un même événement peut donc arriver plusieurs fois : utilisez id (ou data.id + type) pour ne traiter qu'une fois.
Vérifier la signature (obligatoire)
v1 = HMAC-SHA256 de "{t}.{corps brut}" avec votre WEBHOOK_SECRET. Utilisez le corps brut reçu, avant tout parsing JSON. Rejetez si t a plus de 5 minutes.
Node.js (Express)
import crypto from 'node:crypto';
import express from 'express';
const app = express();
app.post(
'/api/paygate/webhook',
express.raw({ type: 'application/json' }),
(req, res) => {
const header = req.get('PayGate-Signature') || '';
const { t, v1 } = Object.fromEntries(
header.split(',').map((p) => p.split('=')),
);
const expected = crypto
.createHmac('sha256', process.env.WEBHOOK_SECRET)
.update(`${t}.${req.body.toString('utf8')}`)
.digest('hex');
const valid =
v1 &&
v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
if (!valid || Math.abs(Date.now() / 1000 - Number(t)) > 300)
return res.sendStatus(400);
const event = JSON.parse(req.body.toString('utf8'));
if (event.data.mode !== process.env.PAYGATE_MODE)
return res.sendStatus(200); // 'live' en production
if (event.type === 'payment.completed') {
// marquer la commande event.data.reference comme payée (si pas déjà fait)
}
res.sendStatus(200);
},
);
PHP
<?php
$payload = file_get_contents('php://input');
parse_str(str_replace(',', '&', $_SERVER['HTTP_PAYGATE_SIGNATURE'] ?? ''), $sig);
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $payload, getenv('WEBHOOK_SECRET'));
if (!isset($sig['v1']) || !hash_equals($expected, $sig['v1']) || abs(time() - (int)$sig['t']) > 300) {
http_response_code(400); exit;
}
$event = json_decode($payload, true);
if ($event['data']['mode'] !== getenv('PAYGATE_MODE')) { http_response_code(200); exit; } // 'live' en production
if ($event['type'] === 'payment.completed') {
// marquer la commande $event['data']['reference'] comme payée (si pas déjà fait)
}
http_response_code(200);
9. Erreurs
Format commun :
{
"error": {
"code": "validation_error",
"message": "Paramètres invalides.",
"details": [{ "field": "amount", "message": "…" }]
}
}
| HTTP | code |
Cause |
|---|---|---|
| 400 | invalid_json |
Corps non JSON |
| 401 | missing_credentials / invalid_credentials |
En-têtes absents ou identifiants invalides / révoqués |
| 403 | merchant_suspended |
Compte suspendu |
| 403 | payouts_disabled |
Payouts non activés sur votre compte |
| 409 | insufficient_balance |
Solde insuffisant pour ce payout |
| 403 | daily_limit_exceeded |
Plafond journalier atteint (voir details.remaining_today) |
| 403 | payment_amount_limit_exceeded |
Montant supérieur au maximum par paiement de votre compte (voir details.max_amount) |
| 429 | payment_interval_not_elapsed |
Délai minimal entre deux paiements live non écoulé (voir details.retry_after_seconds) |
| 429 | payout_interval_not_elapsed |
Délai minimal entre deux payouts live non écoulé (voir details.retry_after_seconds) |
| 403 | subscriptions_disabled |
Abonnements non activés sur votre compte |
| 409 | subscription_limit_reached |
Nombre maximal d'abonnements en cours atteint |
| 404 | payment_not_found |
Paiement inexistant (ou d'un autre compte) |
| 409 | reference_conflict |
reference déjà utilisée avec un autre montant |
| 422 | validation_error |
Champ manquant ou invalide (voir details) |
| 502 | provider_* |
L'opérateur a refusé ou n'a pas répondu — vous pouvez réessayer avec la même reference |
| 503 | mode_not_configured |
Mode live pas encore activé |
10. Tester en sandbox
Avec vos identifiants test (app_test_… / sk_test_…), tout se passe dans notre bac à sable : aucun argent réel. Validez tout le parcours avant de demander vos identifiants live.
Ce qu'il vous faut
- Vos identifiants de test :
APP_ID,APP_SECRET,WEBHOOK_SECRET. - Un client fictif (e-mail ou téléphone + mot de passe), que nous vous fournissons avec vos accès. Sur la page de paiement sandbox, on ne paie pas avec un vrai numéro Orange Money ou Wave : on se connecte avec ce compte de test.
- Une URL webhook joignable en HTTPS. Pas encore de serveur ? Utilisez une URL de webhook.site et communiquez-la-nous : vous y verrez les notifications arriver en direct.
Étapes
- Vérifiez vos identifiants
Réponse attendue :curl https://paygate-api.clarizegroup.com/v1 -H "X-App-Id: $APP_ID" -H "X-App-Secret: $APP_SECRET"{"merchant": {...}, "mode": "test"}. - Créez un paiement (
POST /v1/payments, voir section 4) avec unereferenceunique, par ex.TEST-001. - Ouvrez le
checkout_urldans un navigateur, connectez-vous avec le client fictif et validez le paiement. - Recevez le webhook
payment.completedsur votre URL et vérifiez sa signature (section 8). - Contrôlez le statut :
GET /v1/payments/{id}doit renvoyer"status": "completed". - Testez aussi les cas d'échec : annulez sur la page de paiement (retour sur
cancel_url), renvoyez la mêmereference(même paiement,200), puis la mêmereferenceavec un autre montant (409 reference_conflict).
Checklist avant le passage en live
- La commande est validée uniquement à réception du webhook (ou après
GET /v1/payments/{id}), jamais surreturn_url. - La signature du webhook est vérifiée avec le secret live, les doublons sont ignorés et
data.modevautlive. -
APP_SECRETn'est présent que côté serveur. - Les erreurs
502 provider_*sont réessayées avec la mêmereference.
Quand tout est validé, demandez-nous vos identifiants live (app_live_… / sk_live_…) : il suffit ensuite de les remplacer dans votre configuration, sans autre changement de code.
Disponibilité de Bictorys
Les encaissements Bictorys sont disponibles pour Wave Sénégal et Orange Money Sénégal. En routage automatique live : Mlouma, puis Bictorys, puis PayDunya, selon les activations, plafonds et délais de chaque fournisseur. PAYIN_PROVIDER=paydunya force PayDunya. Le choix explicite provider: "bictorys" ne bascule pas vers un autre fournisseur en cas d’indisponibilité. Le sandbox Bictorys nécessite son activation et ses clés de test.