Aller au contenu
Clarize PayGateClarize PayGate
Développeurs

Une seule API pour encaisser partout

Orange Money, Wave, Free Money, carte bancaire : vous créez un paiement, votre client paie, vous recevez un webhook signé.

URL de base de l’API https://paygate-api.clarizegroup.com

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_SECRET live. 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_SECRET dans 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

  1. Votre serveur crée un paiement → vous recevez un checkout_url.
  2. Vous redirigez le client vers checkout_url (notre page de paiement).
  3. Le client paie. Il est renvoyé vers votre return_url (ou cancel_url s'il annule).
  4. Nous vous envoyons un webhook payment.completed sur votre serveur.
  5. 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 :

  1. Vous créez le payout → le montant est immédiatement réservé sur votre solde ; statut pending_approval.
  2. Notre équipe le valide (contrôle anti-fraude), puis le transfert est exécuté → processing puis completed.
  3. S'il est refusé (rejected) ou échoue chez l'opérateur (failed), le montant est recrédité sur votre solde.
  4. Vous recevez un webhook payout.completed, payout.failed ou payout.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_requested contient data.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_link contient 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

  1. Vérifiez vos identifiants
    curl https://paygate-api.clarizegroup.com/v1 -H "X-App-Id: $APP_ID" -H "X-App-Secret: $APP_SECRET"
    
    Réponse attendue : {"merchant": {...}, "mode": "test"}.
  2. Créez un paiement (POST /v1/payments, voir section 4) avec une reference unique, par ex. TEST-001.
  3. Ouvrez le checkout_url dans un navigateur, connectez-vous avec le client fictif et validez le paiement.
  4. Recevez le webhook payment.completed sur votre URL et vérifiez sa signature (section 8).
  5. Contrôlez le statut : GET /v1/payments/{id} doit renvoyer "status": "completed".
  6. Testez aussi les cas d'échec : annulez sur la page de paiement (retour sur cancel_url), renvoyez la même reference (même paiement, 200), puis la même reference avec 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 sur return_url.
  • La signature du webhook est vérifiée avec le secret live, les doublons sont ignorés et data.mode vaut live.
  • APP_SECRET n'est présent que côté serveur.
  • Les erreurs 502 provider_* sont réessayées avec la même reference.

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.