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 LuckyFastPay dans notre environnement Sandbox, avant votre passage en production.

format

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 l'onglet Comptes.
Récupérez le code de votre « Compte d'opération ». Il commence généralement par ACC_

Emplacement du code du compte d'opération

Renouvellement de la clé secrète

Tout appel aux APIs LuckyFastPay nécessite une clé d'accès (header `X-Secret`) valide liée à votre compte d'opération. Cette clé est temporaire. Vous devez utiliser l'API Renew Secret Key pour l'obtenir ou la renouveler.

Allez dans le menu APIs.
Définissez un mot de passe d'opération fort (requis pour la génération du secret) et récupérez votre « Code URL » (identifiant d'environnement).

Emplacement du mot de passe de la clé API

Webhook de Notification (Callback)

Le Callback est une requête asynchrone que LuckyFastPay envoie à votre serveur pour vous informer du statut final d'une transaction. Vous devez enregistrer une URL publique pour recevoir ces notifications.

Allez dans Urls et cliquez sur «+ Ajouter une URL».
Sélectionnez le type «Callback», renseignez votre URL (HTTPS recommandé) et récupérez le Code URL généré.
Récupérez le code généré

Les URLs en localhost ou 127.0.0.1 ne sont pas acceptées par nos serveurs.

1. Authentification (Génération du Secret)

La première étape consiste à générer votre clé secrète. Cette clé devra être incluse dans l'en-tête `X-Secret` de tous vos appels ultérieurs.

Paramètres requis

Votre Code URL d'environnement (API Secret).
Votre Code du Compte d'Opération (Test).
Votre mot de passe de l'API Renew Secret.

Exemple de requête

Langage

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

Réponse attendue

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

Votre clé secrète a une durée de vie limitée (ex: 3600s). Nous recommandons d'automatiser son renouvellement avant expiration.

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

Pour valider votre intégration, vous devez effectuer au moins 2 simulations de paiement réussies .

Règles de validation :

Authentifiez la requête avec votre clé secrète dans le header `X-Secret`.
Utilisez le code de l'URL de callback créé précédemment.
Utilisez un montant inférieur ou égal à 1000 XAF pour forcer un statut SUCCESS.
Utilisez un format de numéro valide pour cet opérateur.

Exemple de requête

Langage

curl --location 'https://api.luckyfastpay.pro/{YOUR_URL_CODE}/rest' \
  --header 'X-Secret: {SECRET_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"agent":"AGENT-1","amount":200,"callback_url_code":"{CALLBACK_URL_CODE}","customer_account_number":"{MSISDN}","operation_account_code":"{ACCOUNT_CODE}","transaction_type":"PAYMENT","owner_charge":"MERCHANT","operator_owner_charge":"MERCHANT","free_info":"Test intégration","product":"PRODUIT-TEST","operator_code":"ORANGE_RCA","reference":"REF-SUCCESS-01","service":"RESTFUL"}'

Réponse attendue

{
  "status" "PENDING",
  "status_code" "200",
  "operator_code" "ORANGE_RCA",
  "transaction_id" "PAY260226747050",
  "reference" "REF-SUCCESS-01",
  "operation_account_code" "ACC_673B22D1077EA",
  "message" "Votre demande de paiement a été initiée avec succès et est en cours de traitement."
}

Bonnes pratiques

Traitement Asynchrone : Ne vous fiez jamais au statut PENDING de la réponse immédiate pour valider une vente. Attendez toujours la confirmation via le Callback.
Idempotence : Votre système doit être capable de recevoir le même callback plusieurs fois sans doubler les crédits. Utilisez la reference pour vérifier l'état dans votre base de données.
Mécanisme de secours : Si vous ne recevez pas de callback après 3-5 minutes, interrogez systématiquement l'API Check Status.

3. Réception du Callback (Webhook)

Dès que l'opérateur traite la transaction, LuckyFastPay envoie une requête POST à votre URL. Ce payload contient le statut final (SUCCESS ou FAILED).

Exemple de payload

{
  "transaction_id" "PAY260226747050",
  "reference" "REF-SUCCESS-01",
  "status" "SUCCESS",
  "amount" 200,
  "customer_account_number" "074416546",
  "fees" 5,
  "total_amount" 205,
  "owner_charge" "MERCHANT",
  "free_info" "Test intégration",
  "transaction_type" "PAYMENT",
  "status_code" "200",
  "operator_code" "ORANGE_RCA",
  "operation_account_code" "ACC_673B22D1077EA",
  "operator_owner_charge" "MERCHANT",
  "operator_fees" 3,
  "amount_debited" 205,
  "amount_credited" 200
}

Accusé de réception obligatoire

Votre serveur doit répondre à cette requête avec un code 200 OK et un JSON contenant l'écho des identifiants reçus :

{
  "transaction_id" "PAY260226747050",
  "response_code" 200
}

Règles de validation du callback

Echo dynamique : Extrayez le transaction_id et le code du payload reçu pour les renvoyer. Ne fixez pas ces valeurs en dur.
Garantie technique : C'est le seul moyen pour nous de savoir que votre serveur a bien enregistré l'information.
Validation des tests : Vos simulations ne sont validées que si l'accusé de réception est correctement renvoyé.

4. Simulation de Transaction : Scénario Échec

Testez la résilience de votre système. Pour forcer un échec (ex: fonds insuffisants), initiez un paiement avec un montant supérieur à 1000 XAF.

Pour valider cette étape :

Effectuez au moins 2 simulations en échec (ex: 1500 XAF).
Gérez le callback et renvoyez l'accusé de réception comme pour un succès.
Attention le response_code du callback n'est pas un 200 en dur !

Exemple de requête en échec

Langage

curl --location 'https://api.luckyfastpay.pro/{YOUR_URL_CODE}/rest' \
  --header 'X-Secret: {SECRET_KEY}' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"agent":"AGENT-1","amount":200,"callback_url_code":"{CALLBACK_URL_CODE}","customer_account_number":"{MSISDN}","operation_account_code":"{ACCOUNT_CODE}","transaction_type":"PAYMENT","owner_charge":"MERCHANT","operator_owner_charge":"MERCHANT","free_info":"Test intégration","product":"PRODUIT-TEST","operator_code":"ORANGE_RCA","reference":"REF-SUCCESS-01","service":"RESTFUL"}'

5. APIs Complémentaires Obligatoires

Pour finaliser la validation technique, vous devez implémenter :

Demande d'information du client

Permet de vérifier l'identité du détenteur du numéro avant d'initier une transaction. Essentiel pour la lutte contre la fraude.

Voir la documentation

Vérification de statut

Endpoint de secours pour récupérer le statut définitif si le callback n'a pas été reçu.

Voir la documentation

6. Checklist avant mise en production

Avant de basculer en production, vérifiez que :

1

2 succès validés (montant ≤ 1000 XAF).

2

2 échecs validés (montant > 1000 XAF).

3

Accusés de réception conformes sur TOUS les callbacks de test.

4

Appel fonctionnel à l'API Demande d'information du client.

5

Appel fonctionnel à l'API Vérification de statut.