Encaisser
Accepter des paiements
Demande de paiement sur téléphone, QR dynamique, caisse et paybill (C2B), factures, ordres permanents et demandes entre entreprises.
7 min de lecture
Sur cette page
Demande de paiement
POST /partner/stk envoie une demande de paiement sur le téléphone du client. Il approuve avec son code PIN sur son propre appareil ; vous recevez le résultat par webhook.
| Champ | Obligatoire | Description |
|---|---|---|
payer_msisdn | Oui | Téléphone du payeur au format international, par exemple 254708374149. |
amount | Oui | Montant positif dans la devise du compte. |
reference | Non | Votre référence de commande ou de facture, renvoyée dans le webhook. |
callback_url | Non | Remplace votre webhook par défaut pour ce seul débit. |
idem | Non | Clé d'idempotence. Une nouvelle tentative avec la même clé renvoie le débit d'origine. |
Cycle de vie d'un débit
| État | Signification | Événement |
|---|---|---|
pending | Demande envoyée, en attente du client. | charge.created |
authorised | Approuvé, règlement en cours. | |
completed | Argent transféré. transaction contient la référence du grand livre. | charge.completed |
declined | Le client a refusé la demande. | charge.declined |
expired | Aucune réponse avant expiry. | charge.expired |
failed | Impossible d'aboutir (par exemple solde insuffisant). |
Interrogez GET /partner/status?charge_ref=… si un webhook tarde ; ne déduisez jamais un succès de la réponse pending.
Idempotence
Les réseaux connaissent des délais dépassés. Si vous ne savez pas si un débit a été créé, réessayez avec la même valeur idem : vous récupérez le débit d'origine au lieu d'une seconde demande. Utilisez une clé par tentative de paiement, par exemple order-9-attempt-1.
QR dynamique (scanner pour payer)
POST /partner/qr renvoie un PNG en base64 que les clients scannent dans leur application. Affichez-le sur un écran, un reçu ou une facture.
{ "amount": 100, "kind": "buygoods", "recipient": "400200", "reference": "INV-1001" }kind vaut buygoods (caisse), paybill ou send (vers un numéro de téléphone). recipient est par défaut votre propre numéro court.
Caisse et paybill (C2B)
Les clients peuvent aussi payer votre numéro court depuis leur application ou par USSD. Indiquez où envoyer les confirmations avec POST /partner/c2b/register ; chaque paiement arrive ensuite sous la forme d'un événement c2b.confirmation.
Dans le bac à sable, simulez-en un :
curl -s https://pesa-bridge.com/api/bridgepay/v1/partner/c2b/simulate \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"msisdn":"254708374149","amount":250,"bill_ref":"ACC-001"}'Factures
Bill Manager crée des factures avec lignes et taxes. Définissez "send": true pour envoyer aussitôt une demande de paiement au client, ou envoyez-la plus tard avec POST /partner/bills/send.
{
"customer_name": "Jane Doe",
"customer_msisdn": "254708374149",
"tax_pct": 16,
"send": true,
"items": [{ "description": "Consulting", "quantity": 2, "unit_price": 5000 }]
}D'autres façons d'être payé
| Point de terminaison | Fonction |
|---|---|
POST /partner/standingorder | Paiement récurrent d'un client vers votre numéro court ; le client l'autorise dans son application. |
POST /partner/b2b/express | Demander un paiement à une autre entreprise (de caisse à caisse). Aucun argent ne bouge avant son approbation. |
POST /partner/loyalty/pay | Accepter des points de fidélité au paiement ; vous recevez leur valeur en argent. |
GET /partner/balance | Le solde de votre compte d'encaissement. |
Nos ingénieurs répondent aux questions d'intégration. Envoyez-nous la référence de la requête et nous retrouverons l'appel exact.
Contacter le support