Passer au contenu principal
Quand vous appelez l’API Direct Charge, la réponse initiale indique comment le client doit continuer ou ce que votre backend doit attendre. La plupart des flux Direct Charge suivent l’un de ces types de réponse :
  • processing : flux de prompt USSD ou STK
  • redirect : flux de finalisation hébergé par le provider
  • bankTransfer : le client doit faire un virement vers les détails de compte renvoyés
  • pre-otp : code client requis avant la requete

​
1) Flux processing, prompt USSD ou STK

Le client reçoit une demande d’autorisation sur son appareil mobile et confirme avec son PIN.

​
Ce qui se passe

  1. Vous initiez le direct charge.
  2. Le provider envoie un STK push ou un prompt USSD au client.
  3. Le client autorise sur son appareil.
  4. La transaction reste en attente jusqu’à la réponse finale du provider.

​
Comment le détecter

data.action vaut processing. 
{
  "data": {
    "action": "processing",
    "sessionId": "1031-4120-a98f-9357692945",
    "provider": "safaricom-kenya",
    "channel": "mobile-money",
    "reference": "DDC20250812042317DIFMW",
    "amount": 1000,
    "status": "pending",
    "charge": 5,
    "statusDescription": "Awaiting Provider's Feedback"
  },
  "statusCode": 201
}

​
Traitement côté marchand

  • Affichez un état en attente au client.
  • Ne livrez pas sur la reponse initiale.
  • Attendez le webhook ou vérifiez par référence.

​
2) Flux redirect

Le provider renvoie un lien ; le client doit terminer le paiement sur la page ou l’application du provider.

​
Ce qui se passe

  1. Vous initiez le direct charge.
  2. L’API répond avec une URL de redirection.
  3. Le client finalise le paiement sur le canal du provider.
  4. Le client peut ensuite revenir vers votre application ou votre site.

​
Comment le détecter

data.action vaut redirect et l’URL se trouve généralement dans data.data.link. 
{
  "data": {
    "action": "redirect",
    "sessionId": "v1nadjww8lwfxxd7giumi3dyik7pzaxrxqmyvdeuunvixo25jhqf4o6wzuxhjdzg",
    "provider": "orange-ivory-coast",
    "channel": "mobile-money",
    "reference": "DDC20250812042546ICXFC",
    "amount": 10000,
    "status": "pending",
    "charge": 150,
    "statusDescription": "Awaiting Provider's Feedback",
    "data": {
      "link": "https://mpayment.orange-money.com/sx/mpayment/abstract/...",
      "message": "Click link to complete your payment",
      "reference": "DDC20250812042546ICXFC"
    }
  },
  "statusCode": 201
}

​
Traitement côté marchand

  • Redirigez l’utilisateur vers data.data.link.
  • Au retour, vérifiez toujours le statut final côté serveur.
  • Ne marquez jamais le paiement comme réussi uniquement sur la redirection.

​
3) Flux bank transfer

Payfonte renvoie les détails d’un compte bancaire ; le client doit effectuer un virement bancaire pour finaliser le paiement.

​
Ce qui se passe

  1. Vous initiez le direct charge avec un provider bank transfer.
  2. L’API répond avec les détails du compte pour le paiement client.
  3. Vous affichez les détails du compte au client.
  4. Le client envoie le virement depuis son application bancaire ou son canal bancaire.
  5. La transaction reste en attente jusqu’à la confirmation du provider.

​
Comment le détecter

data.action vaut bankTransfer. Les détails de compte sont renvoyés dans data.data. 
{
  "data": {
    "action": "bankTransfer",
    "sessionId": "BT-20250812043010-9D7M2",
    "provider": "bank-transfer-nigeria",
    "channel": "bank-transfer",
    "reference": "ORDER-1002",
    "amount": 10000,
    "status": "pending",
    "charge": 100,
    "statusDescription": "Awaiting customer bank transfer",
    "data": {
      "accountName": "PAYFONTE / Karis Clothing",
      "accountNumber": "0123456789",
      "bankName": "Wema Bank",
      "bankCode": "035",
      "amount": 10000,
      "reference": "ORDER-1002",
      "expiresAt": "2025-08-12T04:45:10.000Z"
    }
  },
  "statusCode": 201
}

​
Traitement côté marchand

  • Affichez clairement les détails de compte renvoyés au client.
  • Incluez le nom de la banque, le numero de compte, le nom du compte, le montant, la reference et l’expiration quand ils sont presents.
  • Gardez le paiement en attente jusqu’à confirmation du statut final par webhook ou vérification.
  • Ne livrez pas uniquement sur la base d’une preuve de virement.

​
4) Flux pre-OTP

Certains providers demandent au client de générer un code provider ou OTP avant l’envoi de la requête de débit.

​
Ce qui se passe

  1. Le client génère un code via l’USSD du provider.
  2. Le client partage ce code avec le marchand.
  3. Le marchand envoie customerInput.customerCode.
  4. Le provider traite le debit.

​
Codes USSD fréquents

  • Orange Ivory Coast : #144*82#
  • Orange Senegal : #144#391#
  • Orange Burkina Faso : *144*4*6*Amount*PIN#
  • Orange Mali : #144#37#

​
Exemple de requête

{
  "reference": "ORDER-1002",
  "amount": 50000,
  "provider": "orange-senegal",
  "webhook": "https://yourapp.com/webhooks/payfonte",
  "narration": "Direct charge test",
  "customerInput": {
    "phoneNumber": "786175702",
    "customerCode": "758610"
  }
}

​
Traitement côté marchand

  • Collectez explicitement l’OTP ou le code client.
  • Validez son format avant l’appel API.
  • Continuez ensuite avec le flux normal de finalisation via webhook ou vérification.

​
Résumé de décision des flux

ActionEtape suivante pour le clientEtape suivante pour le marchand
processingApprouver sur l’appareil, USSD ou STKAttendre le webhook ou la vérification
redirectFinaliser le paiement sur la page providerRediriger puis attendre le webhook ou la vérification
bankTransferVirer le montant vers les détails de compte renvoyésAfficher les détails de compte puis attendre le webhook ou la vérification
Mode de requête pre-otpGénérer et partager le code d’abordEnvoyer le code dans customerInput.customerCode

​
Règles importantes

Les valeurs de montant doivent être des entiers en sous-unités. Les décimales ne sont pas prises en charge.
Voir Spécification des montants.

​
Documentation associée

API Direct Charge

Utilisation des endpoints et définition des champs de requête.

Exemples de payloads

Modèles de payloads spécifiques aux providers.

Webhooks

Confirmez le resultat final de la transaction de maniere asynchrone.