L'API PawaPay Merchant simplifie l'intégration des paiements mobiles à

vos flux de paiement. Elle fournit une API unique et standardisée

permettant de se connecter aux opérateurs de paiement mobile (MMO)
proposant des services de paiement mobile à travers l'[Link]
chapitres suivants présentent certains aspects importants de l'argent
mobile et de l'utilisation des API financières pour vous aider à créer une
intégration de haute qualité que vos clients apprécieront et qui sera facile
à utiliser.

Rappels
L'API marchande pawaPay est asynchrone . Ceci est nécessaire pour
fournir une infrastructure de paiement performante et de qualité, capable
de traiter des millions de paiements chaque [Link] vous effectuez
un paiement ( versement , dépôt , remboursement ), la réponse vous
indiquera si la transaction est acceptée ou refusée . Une transaction peut
être refusée, par exemple, si le même identifiant est utilisé plusieurs fois
ou si le fournisseur est [Link] la réponse confirme que le paiement
a été accepté pour traitement, ce dernier prendra un certain temps
(n'oubliez pas que pour les dépôts, l'utilisateur doit saisir son code PIN sur
son téléphone). Il existe deux façons de connaître le statut final d'un
paiement.

Sondage sur le statut

Premièrement, vous pouvez utiliser le Check Statuspoint de terminaison
correspondant au type de transaction pour vérifier périodiquement l’état
d’un paiement .
Par le biais de rappels
Deuxièmement, vous pouvez configurer des URL de rappel dans le tableau
de bord pawaPay. Un rappel sera automatiquement envoyé à l'URL
configurée dès qu'un paiement aura atteint son statut final. Vous devrez
implémenter un gestionnaire de rappels capable de recevoir les appels de
notre plateforme et de les traiter en conséquence.

Passage en direct

Index de la documentation
Vous trouverez l'index complet de la documentation à l'adresse
suivante : [Link]

Utilisez ce fichier pour découvrir toutes les pages disponibles

avant d'aller plus loin.

Aperçu
Lorsque vous serez prêt à passer de l'environnement de test à la
production, assurez-vous d'utiliser l' URL de base et le jeton
d'authentification corrects . Ce sont les seuls paramètres qui
diffèrent entre l'environnement de test et la production.
Nous vous recommandons de stocker ces paramètres dans la
configuration spécifique à votre environnement.
Si vous utilisez la liste blanche d'adresses IP, assurez-vous
que nos adresses IP y figurent afin que nous puissions vous
rappeler.
 Tests de mise en production
Nous vous recommandons d'activer une fonctionnalité spécifique
pour votre intégration avec pawaPay afin de permettre les tests
de mise en production avant le lancement sur le marché. Cela
vous permettra de tester le flux de bout en bout en production et
de déceler tout problème spécifique à l'environnement avant qu'il
n'affecte vos [Link] tester les paiements en direct, vous
aurez besoin des éléments suivants pour chaque MMO que vous
utilisez :
 Un téléphone et un numéro de téléphone associés au MMO
spécifique.
 Un portefeuille de paiement mobile actif sur ce numéro de
téléphone.
 Un solde disponible sur le portefeuille de monnaie mobile pour
effectuer les tests.
 Préparez-vous à saisir le code PIN sur votre téléphone environ 1 à
20 secondes après avoir initié le paiement via notre API.
Mise à niveau depuis la version V1

Index de la documentation
Vous trouverez l'index complet de la documentation à l'adresse
suivante : [Link]

Utilisez ce fichier pour découvrir toutes les pages disponibles

avant d'aller plus loin.
Quelles sont les nouveautés de la
version 2 de l'API pawaPay ?
Nous avons simplifié l'API pawaPay pour la rendre plus facile à
utiliser. Nous avons également apporté des précisions afin de
permettre aux fournisseurs utilisant différents flux d'autorisation
de paiement de l'intégrer de manière pérenne. Enfin, nous avons
restructuré les données pour faciliter l'ajout de nouvelles
fonctionnalités à l'[Link]-les un par un.

Prise en charge des nouveaux flux

d'autorisation de paiement
Certains fournisseurs n'utilisent pas la saisie du code PIN pour
autoriser les paiements. Ils exigent soit une préautorisation du
client par la génération d'un code OTP, soit une autorisation par
redirection. Ces deux mécanismes sont désormais pris en charge,
ce qui permet une implémentation unique : tous les futurs
fournisseurs utilisant le même mécanisme d'autorisation pourront
en bénéficier sans nouvelle configuration.

Il est désormais plus facile d'éviter les échecs

au démarrage.
Nous avons ajouté toutes les données nécessaires à notre point
de terminaison de configuration active afin d'éviter les échecs de
paiement lors de l'initiation. Ces données comprennent
notamment la gestion correcte des décimales dans les montants,
les limites minimales et maximales des transactions, ainsi que les
informations sur la disponibilité des [Link] plus, le point
de terminaison de prédiction du fournisseur vous aide non
seulement à prédire le fournisseur d'un numéro de téléphone,
mais aussi à nettoyer et valider ce numéro pour garantir sa
validité pour le pays et le fournisseur.

La meilleure expérience client

Le point de terminaison de configuration active inclut également
des informations sur les modalités d'autorisation des paiements
auprès du fournisseur concerné. Cela vous permet d'afficher
précisément les étapes que le client doit suivre et comment gérer
les situations où il ne saisit pas son code PIN à temps, par
exemple.

La configuration active est entièrement

repensée.
Nous avons amélioré le point de terminaison de configuration
active . Sa structure est désormais plus logique et il prend en
charge le filtrage pour obtenir des informations précises sur les
pays et les flux dont vous avez besoin pour votre flux de
[Link] avons ajouté de nombreuses informations
statiques telles que les noms et logos des fournisseurs, les noms
des devises, les codes pays, les drapeaux et les préfixes. Ainsi,
vous pouvez créer un flux de paiement dynamique qui ne
 nécessite aucune modification lorsque de nouveaux fournisseurs
sont activés sur votre compte.

Comment effectuer la mise à niveau

depuis la version V1 ?
Voyons d'abord comment faire en sorte que tout fonctionne
comme avant. Ce n'est pas une tâche complexe.
1

Modifier l'URL de base de l'API

Si vous utilisez toujours [Link] URL de base
pour l'API, il est temps de la modifier comme suit :
 [Link] votre compte sandbox
 [Link] votre compte réel
L'API V2 n'est plus disponible via ce .clouddomaine.
2

Chemins versionnés
Mettez à jour tous vos chemins de requête pour inclure le numéro
de [Link] exemple, les gisements de V1 se situaient à :
POST [Link]
Dans la version 2, il s'agit de :
POST [Link]
3
 demandes financières
Lorsque vous effectuez des appels pour initier des dépôts , des
versements et des remboursements, vous devez :
1. Renommez toutes les occurrences de correspondenten provider.
2. Déplacez-le à l'intérieur de l' accountDetailsobjet.
3. Modifiez la valeur type« within » payerou « from
» en .recipientMSISDNMMO
4. Modifiez le addresscontenu payerou recipientle accountDetails.
5. Remplacez le valuecontenu addresspar phoneNumber.
6. Supprimez le customerTimestampparamètre de la charge utile de la
requête. Ce paramètre a été supprimé.
7. Renommer statementDescriptionen customerMessage.
8. Modifier les métadonnées "fieldName": "orderId"et "fieldValue":
"ORD-123456789"le "orderId": "ORD-123456789"format.
Prenons l'exemple d'un avant et d'un aprè[Link] dans la V1 :
{
"depositId": "919b7674-b61d-4b69-ac58-
d74d2b089192",
"amount": "15",
"currency": "ZMW",
"correspondent": "MTN_MOMO_ZMB",
"payer": {
"type": "MSISDN",
"address": {
"value": "260763456789"
}
},
"customerTimestamp": "2020-02-21T17:32:28Z",
"statementDescription": "Note of 4 to 22
chars",
"metadata": [
{
"fieldName": "orderId",
"fieldValue": "ORD-123456789"
},
{
"fieldName": "customerId",
"fieldValue": "customer@[Link]",
"isPII": true
 }
]
}
Maintenant disponible en V2 :
{
"depositId": "919b7674-b61d-4b69-ac58-
d74d2b089192",
"amount": "15",
"currency": "ZMW",
"payer": {
"type": "MMO", //Was "MSISDN"
"accountDetails": { //Was address
"phoneNumber": "260763456789", //Was
value
"provider": "MTN_MOMO_ZMB" //was
correspondent
}
},
"customerMessage": "Note of 4 to 22 chars",
//Was statementDescription
"metadata": [
{
"orderId": "ORD-123456789" //Was in
annoying format
},
{
"customerId": "customer@[Link]",
//This one as well
"isPII": true
}
]
}
Toutes les demandes financières doivent désormais être
présentées au nouveau [Link] les réponses, les
rappels et les vérifications d'état.
4

Modifications requises dans les réponses

 La seule modification requise dans les réponses concerne les
paiements . Nous ne renvoyons ENQUEUEDplus d'informations sur le
statut lors de l'ouverture de la demande. Les seuls statuts
renvoyés lors de l'ouverture de la demande sont :
 ACCEPTED
 REJECTED
 DUPLICATE_IGNORED
Si vous souhaitez savoir si le paiement a été mis en file d'attente,
vous pouvez utiliser le point de terminaison de vérification de
l'état des paiements .De plus, les
réponses rejectionReasonet errorsont maintenant regroupées
dans failureReason.
{
"status": "REJECTED",
"failureReason": {
"failureCode": "MISSING_PARAMETER",
"failureMessage": "Request does not include
the required parameter 'provider'."
}
}
Nous aborderons ces changements failureReasonplus loin dans ce
[Link] maintenant aux fonctions de rappel et aux
vérifications d'état.
5

Nouveau format de réponse pour les vérifications de statut

Nous avons modifié la charge utile de réponse de la vérification de
statut pour les dépôts , les versements et les
remboursements afin de déterminer plus clairement l'existence
d'un [Link] réponse inclura désormais l'identifiant statusde
la requête avec les valeurs possibles de FOUNDet NOT_FOUND.
Si FOUNDles données de paiement seront disponibles dans le data.
{
"status": "FOUND",
"data": {
"depositId": "919b7674-b61d-4b69-ac58-
d74d2b089192",
 "status": "COMPLETED",
"amount": "15.00",
"currency": "ZMW",
"country": "ZMB",
"payer": {
"type": "MMO",
"accountDetails": {
"phoneNumber": "260763456789",
"provider": "MTN_MOMO_ZMB"
}
},
"customerMessage": "Note of 4 to 22 chars",
"clientReferenceId": "",
"created": "2025-06-02T12:20:35Z",
"providerTransactionId": "09ae7c99-f351-
4c87-a6d2-286337a70d21",
"metadata": {
"orderId": "ORD-123456789",
"customerId": "customer@[Link]"
}
}
}
6

Modifications de la charge utile pour les rappels et les vérifications

d'état
Nous avons
regroupé rejectionReasonles failureReasonréponses errorà un
incident failureReason. Vous pouvez désormais toujours savoir ce
qui s'est passé à partir d'un seul endroit : le site
web [Link] trouverez toutes les informations
nécessaires failureCodesdans notre documentation . Assurez-vous
d'avoir implémenté la gestion [Link]
montant requestedAmountet le depositedAmountmontant ne forment
plus qu'un seul symbole amount, indiquant le montant demandé
pour le dépôt. Si le paiement est effectué FAILED, aucun fonds n'a
été déposé.Les
balises respondedByPayer, receivedByRecipientet suspiciousActivi
tyReportont été supprimées de tous les rappels et vérifications
d'état.L' objet providerTransactionIdest
remplacé correspondentIds. Il contiendra l'identifiant de la
transaction tel que spécifié par le fournisseur (si disponible auprès
de ce dernier).Sinon, toutes les modifications apportées à la
requête seront également répercutées dans les rappels et les
vérifications d'état ; assurez-vous donc que les paramètres
renommés ou obsolètes sont ajusté[Link]:
{
"depositId": "919b7674-b61d-4b69-ac58-
d74d2b089192",
"status": "FAILED",
"requestedAmount": "15",
"depositedAmount": "0",
"currency": "ZMW",
"country": "ZMB",
"correspondent": "MTN_MOMO_ZMB",
"payer": {
"type": "MSISDN",
"address": {
"value": "260763456789"
}
},
"customerTimestamp": "2020-02-21T17:32:28Z",
"statementDescription": "Note of 4 to 22
chars",
"created": "2020-02-21T17:32:29Z",
"respondedByPayer": "2020-02-21T17:32:30Z",
"correspondentIds": {
"MTN_INIT": "ABC123",
"MTN_FINAL": "DEF456"
},
"suspiciousActivityReport": [
{
"activityType": "AMOUNT_DISCREPANCY",
"comment": "There is a discrepancy between
requested and actual deposit amount."
}
],
"failureReason": {
"failureCode": "OTHER_ERROR",
"failureMessage": "Payers address is
blocked"
 },
"metadata": {
"orderId": "ORD-123456789",
"customerId": "customer@[Link]"
}
}
Après la mise en œuvre des modifications ci-dessus, tous les flux
financiers devraient fonctionner comme auparavant. Examinons
maintenant les autres points de terminaison.
7

Rappels, annulations de paiements en attente, etc.

Nous avons unifié les points de terminaison suivants en déplaçant
l'identifiant de paiement respectif du corps de la requête vers les
paramètres de requête :
 Renvoyer le rappel de dépôt
 Renvoyer le rappel de paiement
 Renvoyer le rappel de remboursement
 Annulation du paiement en attente
Par exemple, le renvoi de la notification de dépôt dans la version
1:
POST
[Link]

{
"depositId": "919b7674-b61d-4b69-ac58-
d74d2b089192"
}
Maintenant disponible en V2 :
GET [Link]
callback/919b7674-b61d-4b69-ac58-d74d2b089192

//No body
Examinons maintenant quelques autres points de terminaison et
leur évolution.