Démarrage rapide : votre premier paiement

Avant de commencer#

Créez un compte développeur gratuit sur pesa-bridge.com/developer/signup. Vous recevez aussitôt deux jeux de clés : pk_test_… / sk_test_… pour le bac à sable et pk_… / sk_… pour la production. La clé avec laquelle vous vous authentifiez détermine le mode : le trafic de test ne touche donc jamais à de l'argent réel.

Tous les appels de ce guide utilisent une seule URL de base :

https://pesa-bridge.com/api/bridgepay/v1

1. Obtenir un jeton d'accès#

Échangez votre paire de clés contre un jeton Bearer. Les jetons durent une heure ; demandez-en un nouveau avant la fin de expires_in.

curl -s https://pesa-bridge.com/api/bridgepay/v1/oauth/token \
  -H "Content-Type: application/json" \
  -d '{"client_id":"pk_test_…","client_secret":"sk_test_…"}'

{
  "access_token": "at_9f3…",
  "token_type": "Bearer",
  "expires_in": 3600,
  "mode": "test",
  "sandbox": true
}

2. Indiquer où envoyer les résultats#

Le paiement se termine sur le téléphone du client : le résultat vous parvient donc par webhook. Enregistrez un point de terminaison une seule fois ; la réponse contient un secret de signature affiché une seule fois. Conservez-le : il sert à vérifier chaque livraison.

curl -s https://pesa-bridge.com/api/bridgepay/v1/partner/webhooks/endpoints \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"name":"Orders","url":"https://your-app.com/webhook","events":"*","mode":"test"}'

3. Envoyer une demande de paiement#

Envoyez le numéro du client au format international et le montant. Ajoutez votre propre reference pour rapprocher le résultat de votre commande, et une clé idem pour qu'une nouvelle tentative après un délai dépassé ne débite jamais deux fois.

curl -s https://pesa-bridge.com/api/bridgepay/v1/partner/stk \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"payer_msisdn":"254708374149","amount":250,"reference":"INV-1001","idem":"inv-1001-1"}'

{
  "charge_ref": "STK0000123",
  "state": "pending",
  "amount": 250.0,
  "expiry": "2026-09-27T12:05:00Z"
}

Le client approuve sur son propre téléphone avec son code PIN. Vous ne le voyez jamais et ne le manipulez jamais.

4. Recevoir le résultat#

Lorsque le débit est finalisé, nous envoyons par POST un événement signé à votre point de terminaison :

POST /webhook
X-PesaBridge-Event: charge.completed
X-PesaBridge-Signature: …e9 (hex HMAC-SHA256 of the raw body)

{
  "event": "charge.completed",
  "charge_ref": "STK0000123",
  "reference": "INV-1001",
  "amount": 250.0,
  "currency": "KES",
  "payer": "254708374149",
  "state": "completed",
  "transaction": "PB7H2K9Qmn"
}

Vérifiez la signature, marquez la commande comme payée et répondez par n'importe quel code 2xx. Voir Webhooks pour du code de vérification dans plusieurs langages.

5. Ou vérifier le statut vous-même#

Les webhooks font foi, mais vous pouvez toujours interroger l'API :

curl -s "https://pesa-bridge.com/api/bridgepay/v1/partner/status?charge_ref=STK0000123" -H "Authorization: Bearer $TOKEN"

{ "charge_ref": "STK0000123", "state": "completed", "transaction": "PB7H2K9Qmn" }

Étapes suivantes#

• Authentification : modes des clés, mise en cache et rotation des jetons.
• Accepter des paiements : QR, caisse et paybill (C2B), factures et ordres permanents.
• Paiement hébergé : une page de paiement sans développement front-end.
• Liste de contrôle de mise en production : tout ce qu'il faut confirmer avant de passer aux clés live.