DÉVELOPPEURS · PREMIERS PAS

Un paiement.
Une intégration.

Initialisez la transaction depuis votre serveur, présentez le checkout au client, puis attendez la confirmation du prestataire avant de valider votre commande.

01. Authentifier la requête

Envoyez votre clé marchande dans x-api-key. Conservez-la côté serveur. Ajoutez un en-tête Idempotency-Key unique par opération et réutilisez-le lors d’une nouvelle tentative de la même requête.

POST /v1/payments
Content-Type: application/json
x-api-key: <votre-clé-marchande>
Idempotency-Key: <identifiant-unique>

02. Initialiser le paiement

Exemple de corps JSON pour Airtel Money au Gabon. Remplacez le téléphone et la référence par ceux de votre transaction. Le montant est exprimé en unités mineures : pour XAF, 25000 correspond à 25 000 FCFA.

POST /v1/payments

{
  "orderId": "CMD-0241",
  "amount": 25000,
  "currency": "XAF",
  "countryCode": "GA",
  "paymentMethod": "MOBILE_MONEY",
  "mobileMoneyOperator": "AIRTEL",
  "customer": { "phone": "+24177000000" }
}

La réponse HTTP 202 signifie que la demande a été acceptée. Elle ne constitue pas une confirmation de paiement. La réponse contient l’identifiant du paiement, son statut et les informations de checkout adaptées au prestataire.

03. Confirmer avant de livrer

Consultez GET /v1/payments/:id ou configurez votre webhook marchand dans le tableau de bord. Attendez le statut SUCCEEDED avant de considérer la commande comme payée.

Lorsqu’un secret webhook est configuré, l’en-tête X-BoohPay-Signature contient une signature sha256=…. Vérifiez le HMAC SHA-256 du corps brut avec votre secret avant de traiter l’événement. Rendez votre traitement idempotent : un événement peut être livré plusieurs fois.

Le choix de la solution de paiement

Par défaut, les cartes passent par Stripe, le Mobile Money au Gabon par eBilling, et le Mobile Money des autres pays par Moneroo. Votre serveur peut demander explicitement un prestataire compatible, dont PViT, avec le champ provider.

Le choix actuel repose sur le pays, la méthode et le prestataire demandé. Il ne compare pas les coûts ni la disponibilité en temps réel. Le basculement automatique vers un autre prestataire après un échec n’est pas implémenté dans cette version. Un résultat incertain peut nécessiter une vérification avant toute nouvelle tentative.

La référence complète

La documentation OpenAPI est exposée sur /api à la racine de votre serveur BÖÖHPay. Elle décrit les schémas de réponse et les opérations disponibles sur votre déploiement.