Intégration MYPAYGA

Guide d'intégration de l'API de paiement Mobile Money et Cartes Bancaires.

1.Présentation

Cette API permet à votre plateforme de :

Encaisser des paiements Mobile Money et Cartes Bancaires (ex. Airtel Money) ;
Envoyer de l'argent vers un compte Mobile Money (transferts B2C) ;
Vérifier le statut d'un paiement ou d'un transfert ;
Identifier le réseau d'un numéro de téléphone ;
Recevoir une notification (callback) à la fin de chaque paiement.

Toutes les requêtes POST utilisent le format JSON (Content-Type: application/json).

Base URL

https://api.mypayga.com

Contact

contact@mypayga.com

Clés API

Environnement	Format de la clé
Test	`stest_xxxxx`
Production	`sprod_xxxxx`

🔐 La clé secrète (secretKey), utilisée pour valider les callbacks, vous est transmise directement.

Liste des endpoints

Méthode	Endpoint	Description
GET	`/v1/network`	Identifier le réseau d'un numéro
POST	`/v1/payment`	Initier un paiement
GET	`/v1/payment/status`	Vérifier le statut d'un paiement
POST	`/v1/disbursement/send`	Envoyer de l'argent (B2C)
GET	`/v1/disbursement/status`	Vérifier le statut d'un transfert

2.Vérifier le réseau d'un numéro

GET/v1/network

Paramètres

Paramètre	Description	Exemple
`apikey`	Votre clé API	`sprod_123`
`tel_number`	Numéro à vérifier	`07712345`
`country`	Code pays	`GA`
`type`	Type de compte	`mobile_money`

Exemple de réponse

JSON

{
  "message": "Network Found",
  "network": "Airtel Gabon",
  "mobile_money_code": "AM",
  "mobile_money_svce": "Airtel Money",
  "country": "GA",
  "need_otp": "NO",
  "length_msisdn": 9,
  "statusRequest": 200
}

Le champ mobile_money_code (ici AM) correspond à la valeur à envoyer dans le paramètre network lors d'un paiement ou d'un transfert.

3.Initier un paiement

POST/v1/payment

Corps de la requête

JSON

{
  "urls": {
    "success_url": "https://monsite.com/success-url",
    "callback_url": "https://monsite.com/callback-url",
    "fail_url": "https://monsite.com/fail-url"
  },
  "apikey": "stest_abcd1234",
  "client_phone": "07XXXXXXX",
  "amount": "100",
  "country": "GA",
  "network": "AM",
  "type": "mobile_money",
  "unique_id": "1234",
  "firstname": "Client Prenom",
  "lastname": "Client Nom",
  "email": "email@gmail.com"
}

Champ	Description
`urls.success_url` / `fail_url`	Pages de redirection en cas de succès ou d'échec
`urls.callback_url`	URL qui recevra la notification finale (voir section 7)
`apikey`	Votre clé API
`client_phone`	Numéro du client qui paie
`amount`	Montant à encaisser
`country`	Code pays (GA)
`network`	Code du réseau (ex. AM)
`type`	`mobile_money`
`unique_id`	Identifiant unique de la commande côté marchand
`firstname`, `lastname`, `email`	Informations du client

Exemple de réponse

JSON

{
  "action": null,
  "message": "Request Sent.Final status will be sent to your callback url",
  "unique_id": "24145182105",
  "payment_token": "cb608f63-403b-46ee-81d9-abafa6d26949-1792396812",
  "request_status": 200,
  "transaction": {
    "amount": 300,
    "client_phone": "077123456",
    "country": "GA",
    "currency": "XAF",
    "unique_id": "24145182105"
  }
}

Une réponse request_status: 200 signifie que la demande a bien été envoyée. Le statut final du paiement n'est pas connu à ce stade : il vous est communiqué par callback.

Paiement par carte bancaire : la réponse contient en plus un champ checkout_url. Vous devez rediriger le client vers cette URL pour qu'il finalise son paiement.

4.Vérifier le statut d'un paiement

GET/v1/payment/status

Paramètres

Paramètre	Description
`order_id`	Identifiant de la commande
`apikey`	Votre clé API
`country_code`	Code pays (ex. GA)

Exemple de réponse

JSON

{
  "order_id": "24021742811",
  "unique_id": "bo-9ff25891-9e83-41f9-b8ba-905e02f4703a",
  "order_status": "400",
  "request_status": 200,
  "amount": 100,
  "message": "Transaction Failed",
  "currency": "CFA",
  "created_at": "2024-02-17 18:15:44",
  "payment_method": "Airtel Money"
}

Cet endpoint est utile en complément du callback, par exemple si celui-ci n'a pas été reçu.

5.Disbursement (envoi d'argent)

POST/v1/disbursement/send

Corps de la requête

JSON

{
  "urls": {
    "callback_url": null
  },
  "apikey": "sprod_xxxxx",
  "receiver_account": "074xxxxx",
  "amount": "100",
  "country": "GA",
  "network": "AM",
  "transaction_id": "1234",
  "account_type": "mobile_money",
  "type": "B2C",
  "firstname": "First",
  "lastname": "Last",
  "currency": "FCFA"
}

Champ	Description
`receiver_account`	Numéro du bénéficiaire
`amount`	Montant à envoyer
`network`	Code du réseau (ex. AM)
`transaction_id`	Identifiant unique de la transaction côté marchand
`account_type`	`mobile_money`
`type`	`B2C`
`firstname`, `lastname`	Identité du bénéficiaire
`currency`	Devise (ex. FCFA)

Exemple de réponse

JSON

{
  "request_status": "200",
  "transfert_status": 200,
  "message": "Vous avez envoye 100 FCFA au 065123456",
  "callback_url": null,
  "callback_sent": null,
  "transaction_id": 1234
}

6.Vérifier le statut d'un transfert

GET/v1/disbursement/status

Paramètres

Paramètre	Description
`apikey`	Votre clé API
`transaction_id`	Identifiant de la transaction
`country`	Code pays (GA)

Exemple de réponse

JSON

{
  "order_id": 36280,
  "unique_id": "01cf74d9-931a-4c58-af67-731469c37f6a",
  "order_status": "200",
  "amount": "110.000",
  "message": "Vous avez envoye 110.000 FCFA au 074xxxxxx",
  "currency": "CFA",
  "created_at": "2024-02-20 22:07:32",
  "payment_method": "AM",
  "country": "GA"
}

7.Callback de paiement

À la fin du paiement, notre serveur envoie une requête POST vers votre callback_url.

Exemple de données reçues

JSON

{
  "callback_signature": "signature_a8f92c71d4",
  "order_status": "SUCCESS",
  "unique_id": "CMD_GA_20261019001",
  "amount": 25000,
  "payment_token": "TXN_123456789",
  "payment_method": "Airtel Money",
  "message": "Paiement effectue avec succes",
  "client_phone": "077123456",
  "currency": "XAF"
}

Vérification de la signature

Pour vous assurer que le callback provient bien de nous, recalculez la signature et comparez-la à celle reçue.

Formule : concaténez, dans cet ordre exact et sans séparateur, les champs order_status, unique_id, amount, payment_token, payment_method, message et client_phone, puis calculez un HMAC SHA-512 avec votre clé secrète.

PHP

$string = $order_status . $unique_id . $amount . $payment_token . $payment_method . $message . $client_phone;
$callback_signature = hash_hmac('sha512', $string, $secretKey);

Où trouver la signature reçue ?

Recommandé dans le header HTTP X-Callback-Signature.
La signature est aussi présente dans le corps (callback_signature), mais ce champ sera supprimé dans une prochaine mise à jour.

⚠️ Implémentez dès maintenant la lecture de la signature via le header X-Callback-Signature.

Bonnes pratiques

Vérifiez que votre unique_id correspond à une commande connue et que le montant est cohérent avant de valider la commande.
Répondez rapidement (HTTP 200) et traitez chaque callback de manière idempotente, car une notification peut être renvoyée.

8.Codes opérateurs et statuts

Opérateur	Network	Type
Airtel Money	`AM`	`mobile_money`
Moov Money	`MC`	`mobile_money`
MTN	`MTN`	`mobile_money`
Orange Money	`OM`	`mobile_money`
Carte Bancaire	`CB`	`card`

9.Statuts des transactions

Pour un paiement, le champ order_status du callback indique le statut réel de la commande. Pour un transfert, le code à prendre en compte est transfert_status, que vous le receviez en réponse directe ou par callback.

Code	Statut	Remarque
`200`	Succès	Statut définitif : il ne change plus.
`202`	En attente (pending)	Transaction en cours de traitement.
`400`	Échec	Dans de rares cas, un statut 400 peut passer à 200 après vérifications.

Tous les autres codes nécessitent la vérification de la transaction. Merci de nous contacter en cas de doute sur une transaction avant tout remboursement.

10.Tests et validation de l'intégration

Avant le passage en production :

Utilisez votre clé de test (stest_...) pour effectuer des transactions de test.
Vérifiez que votre callback_url est joignable publiquement et que la validation de signature fonctionne.
Testez les cas de succès et d'échec, ainsi que la vérification de statut.
Une fois l'intégration validée, remplacez la clé de test par votre clé de production (sprod_...).

Numéros de test : pour le Mobile Money, les numéros utilisés pour les tests doivent d'abord être déclarés dans votre espace marchand.

Pour la carte bancaire, il n'existe pas de simulation de test. L'intégration se fait directement en production après succès de l'intégration du Mobile Money.