Ce guide explique le flux de paiement complet dans Yabetoo, de la création d’une intention de paiement à la réception de la confirmation via les webhooks.
Vue d’ensemble
Le flux de paiement Yabetoo suit un processus en deux étapes qui vous donne un contrôle total sur le moment et la manière dont les paiements sont capturés.
Étape 1 : Créer une intention de paiement
Une intention de paiement représente votre intention de collecter un paiement. Elle suit le cycle de vie du paiement et stocke les informations sur la transaction.
curl https://pay.sandbox.yabetoopay.com/v1/payment-intents \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"amount": 5000,
"currency": "xaf"
}'
- Aucun argent n’a été transféré
- L’intention est au statut
pending
- Vous avez un
client_secret pour l’étape suivante
Étape 2 : Confirmer l’intention de paiement
La confirmation déclenche le paiement réel. Vous fournissez les détails du moyen de paiement du client (informations Mobile Money).
curl https://pay.sandbox.yabetoopay.com/v1/payment-intents \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"client_secret": "pi_xxx_secret_yyy",
"first_name": "Jean",
"last_name": "Dupont",
"receipt_email": "[email protected]",
"payment_method_data": {
"type": "momo",
"momo": {
"country": "cg",
"msisdn": "+242066594470",
"operator_name": "mtn"
}
}
}'
- Le client reçoit une notification push sur son téléphone
- Il entre son code PIN pour autoriser le paiement
- Yabetoo attend la réponse du fournisseur Mobile Money
Étape 3 : Gérer le résultat
Réponse synchrone
La requête de confirmation retourne immédiatement avec le statut du paiement :
{
"intent_id": "pi_9aATHBv8UXuD6H5qrSav",
"amount": 5000,
"currency": "xaf",
"status": "succeeded",
"captured": true
}
Notification Webhook
Pour plus de fiabilité, écoutez toujours les webhooks. Yabetoo envoie un événement intent.completed lorsque le paiement réussit :
// Votre endpoint webhook
app.post("/webhook", (req, res) => {
const event = req.body;
if (event.type === "intent.completed") {
const payment = event.data;
// Mettre à jour votre base de données
// Envoyer une confirmation au client
}
res.status(200).send("OK");
});
Statuts de paiement
| Statut | Description |
|---|
pending | Intention de paiement créée, pas encore confirmée |
processing | Le paiement est en cours de traitement par le fournisseur Mobile Money |
succeeded | Paiement effectué avec succès |
failed | Paiement échoué (fonds insuffisants, rejeté, etc.) |
Codes d’erreur courants
Lorsqu’un paiement échoue, vous pouvez recevoir l’un de ces codes d’erreur :
| Code | Description |
|---|
LOW_BALANCE_OR_PAYEE_LIMIT_REACHED_OR_NOT_ALLOWED | Fonds insuffisants, limite de transaction atteinte, ou transaction non autorisée |
TIMEOUT | Le client n’a pas confirmé le paiement à temps |
Gérez toujours l’erreur LOW_BALANCE_OR_PAYEE_LIMIT_REACHED_OR_NOT_ALLOWED gracieusement en informant le client que son paiement n’a pas pu être traité en raison d’un solde insuffisant ou de restrictions sur son compte.
Bonnes pratiques
- Vérifiez toujours les webhooks - Ne vous fiez pas uniquement à la réponse synchrone
- Stockez l’ID de l’intention de paiement - Liez-le à votre commande pour le suivi
- Gérez les échecs gracieusement - Affichez des messages d’erreur clairs aux utilisateurs
- Implémentez l’idempotence - Prévenez les paiements en double lors des nouvelles tentatives
Alternative : Sessions de paiement
Pour une intégration plus simple, utilisez les Sessions de paiement. Yabetoo gère l’interface de paiement complète :
curl https://buy.api.yabetoopay.com/v1/sessions \
-X POST \
-H "Content-Type: application/json" \
-H "Authorization: Bearer sk_test_XXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
"total": 5000,
"currency": "xaf",
"accountId": "acct_XXXXXXXX",
"successUrl": "https://votresite.com/success",
"cancelUrl": "https://votresite.com/cancel",
"items": [{
"productId": "prod_123",
"productName": "Plan Premium",
"quantity": 1,
"price": 5000
}]
}'
