Guide d'Intégration – Sandbox

Bienvenue dans la documentation d'intégration. Ce guide vous accompagne pas à pas pour connecter, tester et valider votre implémentation des APIs MyPVit dans notre environnement Sandbox, avant votre passage en production.

Prérequis & Identifiants

Avant de commencer à coder, rassemblez les identifiants uniques. Vous les trouverez dans votre espace marchand.

Code du Compte d'Opération (Environnement Test)

Il identifie le portefeuille de règlement et le groupe d'opérateurs ciblés. En environnement Sandbox, vous devez utiliser le compte Test par défaut.

• Allez dans Comptes.
• Récupérez le code de « Compte TEST ». Il commence par ACC_

Token d'API

Tout appel HTTP oblige une clé d'accès (ou token) valide liée à votre compte d'opération. Pour récupérer cette clé, vous utiliserez l'api Renew Secret Key. Vous devez au préalable définir un mot de passe pour cette api.

• Allez dans APIs. Définissez un mot de passe fort et conservez-le.
• Récupérez votre « Code URL ».

Webhook de Notification (Callback)

Le Callback est une requête asynchrone (Webhook) que MyPVit envoie à votre serveur pour vous informer du statut final d'une transaction. Vous devez la configurer.

• Allez dans Urls et cliquez sur le bouton «+Url».
• Sélectionnez le type «Callback» renseignez une URL publique capable de recevoir des requêtes POST.
• Récupérez le code généré.

1. Authentification

Générez votre clé d'accès. Cette clé devra être inclus dans l'en-tête `X-Secret` de vos prochains appels.

Paramètres requis

• Le Code URL (API Secret).
• Le Code du Compte d'Opération (Test).
• Le mot de passe de l'API Secret.

Exemple de requête

curl --location 'https://api.mypvit.pro/v2/{YOUR_URL_CODE}/renew-secret' \
	--header 'Content-Type: application/x-www-form-urlencoded' \
	--data-urlencode 'operationAccountCode={YOUR_OPERATION_ACCOUNT_CODE}' \
	--data-urlencode 'password={YOUR_API_SECRET_PASSWORD}'

Réponse attendue

{
  "operation_account_code": "ACC_XXXXXXXXXXXX",
  "secret": "sk_test_1e803974-0502-41a6-8c44-d2ae79385775",
  "expires_in": 3600
}

2. Simulation de Transaction : Scénario Succès

Vous devez effectuer au moins 2 simulations de paiement succès.

• Authentifiez la requête avec la clé récupérée. Renseignez-la dans le header `X-Secret`.
• Renseignez le code du callback récupéré plus haut.
• Renseignez un opérateur autorisé.
• Utilisez un numéro de téléphone valide de cet opérateur.

Exemple de requête

curl --location 'https://api.mypvit.pro/v2/{YOUR_URL_CODE}/rest' \
  --header 'X-Secret: {SECRET_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"agent":"AGENT-1","amount":150,"callback_url_code":"{CALLBACK_URL_CODE}","customer_account_number":"{MSISDN}","merchant_operation_account_code":"{ACCOUNT_CODE}","transaction_type":"PAYMENT","owner_charge":"CUSTOMER","owner_charge_operator":"CUSTOMER","free_info":"INFORMATION","product":"PRODUIT TEL","operator_code":"AIRTEL_MONEY","reference":"V4cHobJKUt","service":"RESTFUL"}'

Réponse attendue

{
  "status": "PENDING",
  "status_code": "200",
  "operator": "AIRTEL_MONEY",
  "reference_id": "PAY260226747050",
  "merchant_reference_id": "V4cHobJKUt",
  "merchant_operation_account_code": "ACC_673B22D1077EA",
  "message": "Votre demande de paiement V4cHobJKUt a été initiée avec succès et est en cours de traitement. Veuillez patienter le statut définitif de votre transaction"
}

Bonnes pratiques d'intégration

• Traitement Asynchrone : Ne vous fiez jamais au statut PENDING de la réponse API pour valider un paiement. Attendez toujours la confirmation finale (SUCCESS ou FAILED) sur votre URL de notification (Webhook).
• Idempotence : Assurez-vous que votre route de callback est capable de traiter la même notification plusieurs fois sans créditer le client en double. Utilisez toujours votre `merchant_reference_id` pour vérifier si la transaction a déjà été traitée dans votre système.
• Que faire si le Callback n'est pas reçu ? : Ne considérez jamais une transaction comme échouée ou réussie sur la seule base d'une absence de callback. Si vous ne recevez aucune notification après un délai raisonnable (ex: 3 minutes), le statut de la transaction est incertain. Dans ce cas de figure, vous devez impérativement interroger notre API de vérification de statut (Check Status) pour récupérer le statut définitif de la transaction.

3. Réception du Webhook (Callback)

Une fois la transaction traitée par l'opérateur mobile, PVit envoie immédiatement une notification (Webhook) à l'URL de callback que vous avez renseignée lors de la requête initiale. Cette notification contient le statut final et définitif de la transaction (SUCCESS ou FAILED) ainsi que tous les détails de l'opération.

{
  "transactionId": "PAY230226742716",
  "merchantReferenceId": "WKT65454EX",
  "status": "SUCCESS",
  "amount": 150,
  "customerID": "077000000",
  "fees": 3.5,
  "totalAmount": 163.5,
  "chargeOwner": "CUSTOMER",
  "freeInfo": "Test payment",
  "transactionOperation": "PAYMENT",
  "code": 200,
  "operator": "AIRTEL_MONEY",
  "accountOperationCode": "ACC_695XX526XX55",
  "operatorOwnerCharge": "CUSTOMER",
  "operatorFees": 1.5,
  "amountCredited": 150
}

Accusé de réception attendu de votre serveur

Pour confirmer que votre système a bien reçu la notification, votre serveur doit impérativement répondre à notre requête POST avec un code HTTP 200 OK et renvoyer un objet JSON contenant un écho du `transactionId` et du code` reçus.

{
  "transactionId": "PAY230226742716",
  "responseCode": 200
}

4. Simulation de Transaction : Scénario Échec

Il est crucial de tester la résilience de votre application face aux paiements refusés (fonds insuffisants, annulation par le client, etc.). Pour forcer un scénario d'échec, il vous suffit d'initier une requête de paiement avec un montant strictement supérieur à 1000 XAF.

Pour valider cette étape de votre intégration, vous devez impérativement :

1. Effectuer au moins deux simulations de transactions en échec.
2. Traiter correctement le Callback associé en renvoyant l'accusé de réception dynamique exigé (tout comme pour le scénario de succès)

Exemple de requête (Montant > 1000 XAF)

curl --location 'https://api.mypvit.pro/v2/{YOUR_URL_CODE}/rest' \
  --header 'X-Secret: {SECRET_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"agent":"AGENT-1","amount":1500,"callback_url_code":"{CALLBACK_URL_CODE}","customer_account_number":"{MSISDN}","merchant_operation_account_code":"{ACCOUNT_CODE}","transaction_type":"PAYMENT","owner_charge":"CUSTOMER","owner_charge_operator":"CUSTOMER","free_info":"Test Echec","product":"PRODUIT TEL","operator_code":"AIRTEL_MONEY","reference":"REF_FAIL_01","service":"RESTFUL"}'

5. APIs Complémentaires Requises

Afin de valider définitivement votre intégration et de garantir un niveau de sécurité et de fiabilité optimal pour vos utilisateurs, l'implémentation des deux API suivantes est obligatoire :

API KYC (Know Your Customer)

Cette api vous permet de vérifier l'identité du client avant d'initier la moindre transaction sensible. C'est une étape indispensable pour sécuriser vos flux et prévenir les risques de fraude

API Check Status (Vérification d'état)

Cette api vous permet de récupérer l'état définitif d'une transaction. Elle agit comme un mécanisme de secours (fallback) absolument essentiel dans le cas où votre système n'aurait pas reçu le Webhook de notification.

6. Checklist d'intégration

Avant de basculer en production, veuillez vous assurer que votre intégration répond parfaitement à nos exigences techniques.

Checklist d'intégration :

• Au moins 2 simulations de succès (montant < 1000 XAF) réalisées et validées.
• Au moins 2 simulations d'échecs (montant > 1000 XAF) réalisées et validées.
• Gestion conforme du Webhook (Callback) pour chaque transaction, avec l'accusé de réception dynamique obligatoire (code HTTP 200 + écho du transactionId et du code).
• Implémentation fonctionnelle de l'API KYC.
• Implémentation fonctionnelle de l'API Check Status.