Intégrez Checkout et suivez vos paiements

Authentification

Utilisez Authorization: Bearer <api_key>. Les clés commencent par fg_sbx_ pour SANDBOX ou fg_prod_ pour PROD. La clé complète est authentifiée ; son préfixe ne suffit pas.

Scopes : checkout:write pour créer, checkout:read pour lire et balance:read pour les soldes. Une clé reste côté serveur.

Préparer votre intégration dans le portail

Dans l’espace Partenaire, ouvrez Développeur pour créer une clé API, configurer les IP publiques de vos serveurs et vos endpoints webhook. Choisissez uniquement les permissions nécessaires et conservez les clés et secrets sur votre serveur.

Dans la liste des clés API, utilisez « Modifier les permissions » pour activer ou retirer des permissions sans changer la clé utilisée par votre intégration. La valeur confidentielle n’est pas réaffichée. Décocher toutes les permissions bloque les appels de cette clé sans la révoquer. Pour la création comme pour la modification, ne sélectionnez que les permissions nécessaires.

Autoriser les IP de vos serveurs

Configurez les IP publiques de sortie de vos serveurs dans Partenaire > Développeur > Whitelist IP. IPv4, IPv6, CIDR et plages sont acceptés : une entrée par ligne, 25 lignes par ajout. Sans règle active correspondant à l’IP source, l’API répond HTTP 403 ip-not-allowed. Retirer la dernière règle active bloque les appels API dans cet environnement. Attendez l’activation affichée avant vos tests. Cette liste ne concerne ni les pages de paiement du client, ni votre récepteur webhook.

Transactions du portail

Consultez vos opérations et leurs détails dans l’espace Partenaire. Utilisez les identifiants retournés par l’API pour les retrouver.

Environnements

La même URL https://api.faygaw.org/v1 dessert SANDBOX et PROD. La clé authentifiée détermine le Partner et l’environnement. Aucun paramètre de requête ne permet de changer d’environnement.

Spécificités SANDBOX

Utilisez une clé fg_sbx_ pour SANDBOX et une clé fg_prod_ pour PROD.

Les limites SANDBOX s’appliquent indépendamment par provider et par partenaire. Par défaut, le minimum Checkout est de 10 XOF et le minimum Payout de 100 XOF. Les minimums et plafonds SANDBOX peuvent être adaptés sur demande du partenaire auprès de Faygaw, après validation. Respectez les limites indiquées dans la réponse d’erreur et contactez Faygaw si une adaptation est nécessaire.

Montants et devises

Les montants sont des chaînes exprimées dans la devise demandée. Pour XOF, utilisez un entier positif ; un suffixe décimal composé uniquement de zéros est accepté et normalisé. Conservez les montants retournés comme chaînes pour préserver leur précision.

Idempotence

Idempotency-Key est optionnelle et recommandée pour Checkout : 1 à 191 caractères imprimables, clé à forte entropie, sans expiration. Réutilisez la même clé et le même corps après une réponse incertaine.

Même demande normalisée : HTTP 201 et même session. Corps différent : HTTP 409. La portée est partenaire, environnement, opération et clé. client_reference est obligatoire mais non unique ; conservez aussi le checkout_id.

Limites de requêtes

HTTP 429 indique qu’une limite de requêtes est atteinte. Respectez Retry-After avant de réessayer avec la même clé d’idempotence et le même corps. Ne remplacez pas une opération dont le résultat reste incertain.

Crée un Checkout Direct-Link avec Wave ou Orange Money au Sénégal, en XOF. Retournez launch_options à votre application : WAVE pour Wave ; ORANGE_MONEY et MAXIT pour Orange Money, même si leurs URL sont identiques. Utilisez checkout:write, une IP autorisée et de préférence une Idempotency-Key stable. Sa portée est distincte de Hosted Checkout. Modifier le provider ou le corps avec la même clé entraîne HTTP 409. Après un timeout, conservez la même clé et le même corps. Une réponse 503 peut contenir un snapshot checkout : conservez son identifiant. Confirmez le paiement avec GET ou checkout.paid signé.

Direct-Link Checkout

Idempotence par service

Lancement et confirmation

JSON request

{
  "amount": "100",
  "currency": "XOF",
  "client_reference": "ORDER-001",
  "description": "Order 001",
  "success_url": "https://merchant.example/success",
  "error_url": "https://merchant.example/error",
  "metadata": {
    "language": "fr"
  },
  "payment_method": {
    "provider": "ORANGE_MONEY"
  }
}

HTTP 201

{
  "id": "co_11111111111111111111111111111111",
  "object": "checkout",
  "transaction_id": "txn_22222222222222222222222222222222",
  "environment": "SANDBOX",
  "livemode": true,
  "status": "PROCESSING",
  "amount": "100",
  "currency": "XOF",
  "client_reference": "ORDER-001",
  "description": "Order 001",
  "metadata": {
    "language": "fr"
  },
  "provider": "ORANGE_MONEY",
  "provider_reference": "fg_33333333333333333333333333333333",
  "faygaw_partner_fee": "3",
  "net_amount": "97",
  "created_at": "2026-10-24T21:00:00Z",
  "updated_at": "2026-10-24T21:00:01Z",
  "completed_at": null,
  "launch_options": [
    {
      "type": "DEEPLINK",
      "app": "ORANGE_MONEY",
      "url": "https://s.orange-sonatel.com/example"
    },
    {
      "type": "DEEPLINK",
      "app": "MAXIT",
      "url": "https://s.orange-sonatel.com/example"
    }
  ]
}

Collection Postman Direct-Link

Statuts Checkout et Hosted

OPEN, PROCESSING et UNKNOWN ne prouvent pas un paiement. SUCCEEDED confirme le paiement. FAILED, EXPIRED et CANCELLED sont des états terminaux sans paiement réussi. Utilisez le statut API et les événements signés. Dans Hosted Checkout, le client sélectionne son moyen de paiement. Les URL de retour servent à la navigation et ne constituent jamais une preuve de paiement.

Statuts Payout

PROCESSING : traitement en cours. PENDING : résultat en attente. UNKNOWN : résultat indéterminé. SUCCEEDED : payout réussi. FAILED : payout échoué. Seuls SUCCEEDED et FAILED sont terminaux. UNKNOWN signifie que le résultat final du payout n’est pas encore déterminé. Ne soumettez pas une opération de remplacement. Continuez à récupérer le payout existant jusqu’à obtention d’un statut terminal.

Statuts et suivi d’un Refund

Un refus clair libère les réservations de cette tentative, mais les reprises automatiques peuvent continuer dans la fenêtre de 72 heures. Un résultat incertain conserve les réservations jusqu’à confirmation. À expiration, les envois automatiques s’arrêtent. FAILED décrit un cycle échoué et reste relançable manuellement ; UNKNOWN ne prouve pas l’absence de remboursement. Seul SUCCEEDED confirme la restitution du montant et des frais FAYGAW d’origine.

Une indisponibilité ou un délai dépassé pendant la vérification du remboursement ne constitue pas un échec du Refund et ne produit pas refund.failed. Le résultat reste UNKNOWN et les réservations sont conservées tant que la restitution n’est pas confirmée. Les vérifications reprennent automatiquement dans la fenêtre de 72 heures. À son terme, utilisez la relance manuelle du même Refund ; ne créez pas une demande de remplacement. Continuez le suivi par GET et traitez refund.succeeded dès sa confirmation.

Lire les champs de réponse

Idempotence et réponse perdue

Après un timeout ou une réponse perdue, renvoyez exactement la même demande avec la même Idempotency-Key. La réponse de création initiale est rejouée : utilisez ensuite GET pour l’état actuel. Changer de clé ne crée pas un second remboursement du même paiement.

Notifications et rapprochement

Les événements refund.created, refund.succeeded et refund.failed suivent les règles de signature et livraison des webhooks. Dédupliquez par event.id et appliquez la sequence la plus élevée : 1 à la création, 2 pour le résultat initial, 3 si une confirmation tardive corrige un échec. Aucun événement refund.unknown n’est émis.

Le status historique du Checkout reste SUCCEEDED. Son champ optionnel payment_status distingue PAID de REFUNDED. Rapprochez votre référence métier avec id, original_transaction_id et les notifications reçues.

Configurer vos webhooks dans le backoffice

Dans Partenaire > Développeur > Webhooks, ajoutez une URL HTTPS publique et choisissez au moins un événement : checkout.paid, payout.succeeded, payout.failed, refund.created, refund.succeeded ou refund.failed. Conservez sur votre serveur le secret affiché à sa création ; il est distinct de la clé API. Pendant le renouvellement, ancien et nouveau secrets peuvent coexister. Terminez la rotation après avoir adapté le récepteur. Si le secret n’a pas été sauvegardé, renouvelez-le.

Un endpoint activé reçoit automatiquement les nouveaux événements auxquels il est abonné, sans activation supplémentaire. Vous pouvez modifier ses abonnements sans le recréer.

Consulter le suivi des webhooks

Lorsque le suivi est disponible dans votre espace Partner, ouvrez Développeur > Webhooks. Les données restent limitées à votre compte et à l’environnement sélectionné. Une indisponibilité PROD ne bascule pas vers SANDBOX.

Un événement peut viser plusieurs destinations : un accusé reçu sur une destination ne signifie pas que toutes ont répondu. HTTP 2xx confirme l’accusé HTTP, pas le traitement métier ni la vérification de signature par votre serveur.

Les en-têtes et corps archivés se chargent à la demande. Signature et données sensibles sont masquées dans les réponses, l’affichage et les copies du portail Partner ; le secret de signature n’y est jamais révélé. Un corps vide, une réponse non reçue, un contenu partiel ou trop volumineux et une archive indisponible sont des situations distinctes. Certains contenus non structurés sont retenus pour protéger les données sensibles.

Le JSON affiché peut être mis en forme et expurgé : il ne remplace jamais les octets bruts reçus par votre serveur pour vérifier HMAC. Les contrôles signalés comme indisponibles ne déclenchent aucun envoi. La consultation et les erreurs de livraison ne modifient pas votre Checkout, Payout ou Refund.

Lorsqu’ils sont disponibles et autorisés sur votre compte, Tester et Renvoyer lancent des demandes ponctuelles. Depuis Santé, Tester ouvre une fenêtre avec la destination et le bouton Lancer le test. Aucun diagnostic ne part avant ce clic. Ce clic demande immédiatement le démarrage du test ; une indisponibilité temporaire peut retarder sa prise en charge. Le test exécute cinq contrôles : joignabilité du serveur, validité et expiration du certificat SSL, rejet d’une signature invalide, acceptation d’une requête correctement signée, et réponse en moins de 15 secondes. Le diagnostic envoie deux requêtes synthétiques webhook.test, sans montant ni opération financière : une avec une signature volontairement invalide, puis une avec une signature valide et fraîche. Votre récepteur doit reconnaître ce type de diagnostic sans exécuter d’action financière. Le récepteur de la boutique de test distingue les événements Checkout, Payout et Refund ; seul checkout.paid déclenche sa confirmation de commande. HTTP 401 ou 403 est attendu pour la signature invalide ; un autre rejet, par exemple HTTP 400 ou 404, ne prouve pas le contrôle de signature et reste à vérifier. Une redirection n’est jamais suivie.

Le modal affiche les étapes réellement enregistrées : En attente, En cours, Réussi, À vérifier, Échec ou Non exécuté, puis le résultat final. Fermer le modal arrête le suivi à l’écran, pas le traitement. Reprendre le suivi ne renvoie aucune requête. Une réponse perdue n’est pas présentée comme un succès et n’est pas rejouée automatiquement.

Le taux d’erreur porte sur les tentatives de livraison réelles terminées au cours des 7 derniers jours, hors diagnostics. Il est vert à 0 %, en avertissement au-dessus de 0 % jusqu’à 20 % inclus, et rouge au-delà de 20 % avec « Taux d’erreur élevé — Vérifiez votre endpoint ». Sans tentative de livraison réelle, le taux affiche « Aucune donnée » et ne contribue pas au score Santé. Les cinq contrôles de diagnostic réussis donnent donc 5/5 en vert. Dès que des tentatives réelles existent, le taux historique devient le sixième critère. Un contrôle de diagnostic absent ou non terminé reste comptabilisé ; sans diagnostic disponible ou pendant son exécution, le score reste neutre.

Renvoyer cible une livraison et sa destination d’origine : mêmes octets et identifiant d’événement, nouvelle signature et nouvel horodatage. Le renvoi peut servir après un accusé déjà reçu. Il ne rejoue aucun paiement, ne modifie aucun solde et ne prolonge pas les reprises automatiques. Confirmez l’événement et la destination ; votre récepteur doit dédupliquer sur l’identifiant de l’événement.

Retirer un type d’événement des abonnements de votre endpoint empêche les futurs envois et les reprises automatiques de ce type. Les livraisons concernées sont arrêtées sans effacer leur historique. Un renvoi manuel de cet événement exige aussi un abonnement actif. Une requête HTTP déjà partie peut encore recevoir sa réponse ; un accusé déjà reçu reste acquis. Réinscrire un événement ne réarme pas les livraisons annulées. Les diagnostics webhook.test restent indépendants des abonnements métier.

Une demande enregistrée n’est pas encore une livraison réussie. Des permissions et limites s’appliquent ; le délai de réessai est indiqué lorsqu’il peut être calculé. Une URL modifiée ou un endpoint inactif bloque l’envoi. Après un résultat incertain, vérifiez vos journaux avant de demander un nouvel envoi. Arrêter le suivi dans le modal n’annule pas la demande ; reprendre son état ne crée pas un nouvel envoi. Les tests ponctuels sont séparés des statistiques de livraison des événements métier.

En SANDBOX, les endpoints actifs des partenaires actifs reçoivent également un diagnostic quotidien avec les mêmes cinq contrôles et les mêmes requêtes synthétiques webhook.test. Les passages sont répartis sur la journée UTC et peuvent être retardés en cas de charge ou d’indisponibilité. Une interruption ne rejoue pas toutes les journées manquées. Le dernier résultat applicable à la configuration courante apparaît dans Santé ; un test ponctuel reste disponible. Ces diagnostics sont exclus des statistiques de livraison métier.

Événements partenaires

checkout.paid confirme un Checkout payé. payout.succeeded confirme un Payout réussi. payout.failed confirme un Payout échoué. Il n’existe pas d’événement payout.unknown. L’échec d’une tentative isolée ne constitue pas un échec final du Checkout.

Livraison et reprises

Une réponse 2xx acquitte la livraison. En cas d’échec ou de réponse perdue, le même événement peut être livré à nouveau avec le même corps, un nouveau timestamp et une nouvelle signature. Les redirections ne sont pas suivies. Les reprises automatiques peuvent se poursuivre pendant 72 heures à compter du premier envoi. Désactiver ou supprimer un endpoint arrête ses reprises en attente. Dédupliquez les événements, enregistrez-les durablement puis acquittez rapidement ; traitez séparément les tâches longues.

Erreurs

Utilisez error.code, le statut HTTP et request_id pour diagnostiquer une réponse. HTTP 401 indique un problème d’authentification, 403 une autorisation insuffisante, 404 une ressource non accessible, 409 un conflit et 429 une limite atteinte. Un échec réseau ou HTTP 503 ne prouve jamais qu’un paiement a échoué.

{
  "error": {
    "code": "invalid-request",
    "message": "The request is invalid.",
    "request_id": "example-request-id"
  }
}

Metadata

metadata permet d’associer de petites références métier à une ressource. Ces valeurs sont restituées dans les webhooks.

Bonnes pratiques

• Conservez checkout_id, transaction_id, client_reference, refund_id et la clé d’idempotence avec votre commande.
• Après une réponse perdue ou un timeout, réessayez avec exactement la même clé et le même payload. Une nouvelle clé ne résout pas une incertitude financière.
• La réponse rejouée d’un POST peut être celle de l’admission initiale : consultez le GET pour l’état courant.
• Ne considérez jamais PROCESSING ou UNKNOWN comme un remboursement réussi ou définitivement échoué.
• Vérifiez l’état serveur ; une redirection navigateur ne prouve pas un paiement ou un remboursement.
• Gardez les clés API et secrets de signature côté serveur. Ne journalisez pas les tokens ni le fragment du lien Hosted.
• Vérifiez la signature du webhook sur les octets bruts, son timestamp et l’environnement attendu.
• Dédupliquez les notifications par event_id. Conservez-les durablement avant de répondre 2xx, puis traitez les tâches longues en arrière-plan.
• Tolérer une livraison répétée ou désordonnée ne doit jamais produire un second effet métier. Consultez le GET en cas de notification absente ou incohérente. Pour les notifications Refund, conservez la séquence la plus élevée déjà traitée. Une confirmation tardive peut corriger un échec précédent ; consultez GET pour résoudre une contradiction.
• Respectez Retry-After lorsqu’il est fourni après un HTTP 429. Conservez le X-Request-Id pour faciliter une demande au support.