Transactions
Créer des transactions
La création d’une transaction se fait en plusieurs processus.
1 - Requête de création de la transaction
Vous devez commencer par envoyer une requête de création de transaction via l’API. Cette requête doit contenir les
paramètres tels que le montant de la transaction, sa description et la devise à utiliser pour celle-ci en plus des
informations du client concerné par cette opération.
Vous avez donc :
description
: pour donner une brève description de l’objet de la transactionamount
: définir le montant de la transaction. Ce montant doit toujours être un nombre entiercurrency
: préciser la devise à utiliser pour la transactioncallback_url
: le lien de retourcustomer
: préciser le client avec lequel doit se faire la transaction
Pour cet attribut, il faut soit indiquer le numéro ISO ou l’ISO. Référez-vous au tableau des devises disponibles.
Vous avez la possibilité à ce niveau de créer en même temps que la transaction,
un nouveau client à qui sera automatiquement affecté cette transaction si vous ne l’avez pas encore enregistré
auparavant.
Dans ce cas vous devez indiquer nom, prénom, e-mail et numéro de téléphone.
Utilisez le code ci-dessous pour adresser votre requête via l’API.
curl -X POST \
https://sandbox-api.fedapay.com/v1/transactions \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json' \
-d '{
"description" : "Transaction for [email protected]",
"amount" : 2000,
"currency" : {"iso" : "XOF"},
"callback_url" : "https://maplateforme.com/callback",
"customer" : {
"firstname" : "John",
"lastname" : "Doe",
"email" : "[email protected]",
"phone_number" : {
"number" : "+22997808080",
"country" : "bj"
}
}
}'
/* Remplacez VOTRE_CLE_API par votre véritable clé API */
\FedaPay\FedaPay::setApiKey("VOTRE_CLE_API_SECRETE");
/* Précisez si vous souhaitez exécuter votre requête en mode test ou live */
\FedaPay\FedaPay::setEnvironment('sandbox'); //ou setEnvironment('live');
/* Créer la transaction */
\FedaPay\Transaction::create(array(
"description" => "Transaction for [email protected]",
"amount" => 2000,
"currency" => ["iso" => "XOF"],
"callback_url" => "https://maplateforme.com/callback",
"customer" => [
"firstname" => "John",
"lastname" => "Doe",
"email" => "[email protected]",
"phone_number" => [
"number" => "+22997808080",
"country" => "bj"
]
]
));
const { FedaPay, Transaction } = require('fedapay')
/* Remplacez VOTRE_CLE_API par votre véritable clé API */
FedaPay.setApiKey("VOTRE_CLE_API_SECRETE");
/* Précisez si vous souhaitez exécuter votre requête en mode test ou live */
FedaPay.setEnvironment('sandbox'); //ou setEnvironment('live');
/* Créer la transaction */
const transaction = await Transaction.create({
description: 'Description',
amount: 2000,
callback_url: 'https://maplateforme.com/callback',
currency: {
iso: 'XOF'
},
customer: {
firstname: 'John',
lastname: 'Doe',
email: '[email protected]',
phone_number: {
number: '97808080',
country: 'BJ'
}
}
});
Dans le cas où votre client est déjà répertorié, donnez juste en paramètre son identifiant (ID) ou son email.
L'ID et l'adresse email de votre client se trouvent au niveau de votre tableau de bord dans les détails.
curl -X POST \
https://sandbox-api.fedapay.com/v1/transactions \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json' \
-d '{
"description" : "Transaction for [email protected]",
"amount" : 2000,
"currency" : {"iso" : "XOF"},
"callback_url" : "https://maplateforme.com/callback",
"customer" : {
"email" : "[email protected]",
}
}'
/* Remplacez VOTRE_CLE_API par votre véritable clé API */
\FedaPay\FedaPay::setApiKey("VOTRE_CLE_API_SECRETE");
/* Précisez si vous souhaitez exécuter votre requête en mode test ou live */
\FedaPay\FedaPay::setEnvironment('sandbox'); //ou setEnvironment('live');
/* Créer la transaction */
\FedaPay\Transaction::create(array(
"description" => "Transaction for [email protected]",
"amount" => 2000,
"currency" => ["iso" => "XOF"],
"callback_url" => "https://maplateforme.com/callback",
"customer" => [
"email" => "[email protected]" /* ou "id" => 105 */
]
));
const { FedaPay, Transaction } = require('fedapay')
/* Remplacez VOTRE_CLE_API par votre véritable clé API */
FedaPay.setApiKey("VOTRE_CLE_API_SECRETE");
/* Précisez si vous souhaitez exécuter votre requête en mode test ou live */
FedaPay.setEnvironment('sandbox'); //ou setEnvironment('live');
/* Créer la transaction */
const transaction = await Transaction.create({
description: 'Description',
amount: 2000,
callback_url: 'https://maplateforme.com/callback',
currency: {
iso: 'XOF'
},
customer: {
email: '[email protected]' /* ou id: 105 */
}
});
Vous pouvez préciser dans cette requête un lien de retour ou callback qui permettra à votre client d'être redirigé vers une page en particulier une fois le règlement de la transaction terminée. Sinon, vous pouvez toutefois vous gardez de fournir ce paramètre.
Il est facultatif contrairement aux autres paramètres de la requête qui eux sont obligatoires pour la création de votre transaction. Notez bien que dans le cas où le lien de retour n’est pas indiqué, votre client devra quitter de façon manuelle la page de paiement à la fin de l’opération.
2- Générer le token et le lien de paiement de la transaction
Une fois la requête de création de la transaction envoyée, le système vous enverra un résumé détaillé des données concernant la transaction avec un identifiant (ID) unique pour celle-ci. Envoyez une nouvelle requête ayant pour seul paramètre l’identifiant reçu via l’API pour générer le lien plus un token ou clé unique pour votre transaction.
Utilisez ce code pour adresser votre requête via l’API.
curl -X POST \
https://sandbox-api.fedapay.com/v1/transactions/ID/token \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json'
$transaction = \FedaPay\Transaction::create(array(...))
$token = $transaction->generateToken();
return header('Location: ' . $token->url);
const transaction = await Transaction.create({...})
const token = await transaction.generateToken();
return redirect(token.url);
3- Redirection vers la page de paiement
Le lien vous permet de rediriger votre client vers la page de paiement sécurisée sur laquelle le client fera le règlement de la transaction.
4- Lien de retour
Ce lien vous retournera également en paramètre l'id et le statut de la transaction. Indiquez-en un si vous le souhaitez, il est facultatif. Le client devra dans ce cas, quitter manuellement la page de paiement.
- Avec le lien de retour indiqué pour une transaction approuvée
https://www.monsite.com/?id=258&status=approved
- Avec le lien de retour indiqué pour une transaction annulée
https://www.monsite.com/?id=259&status=canceled
Dans ces deux exemples, le lien https://www.monsite.com/
est celui que vous avez indiqué comme
callback_url
au moment de la création de votre transaction.
Et il vous renvoie le statut d'une transaction effectuée par le client en paramètres comme suit
?id=259&status=canceled
.
Pour cela, adressez toujours une nouvelle requête directement à l'API pour avoir le véritable statut d'une transaction avec son ID pour faire vos traitements.
5- Récupération des détails d'une transaction
Pour récupérer les informations concernant une transaction donnée, et faire des traitements avec cette dernière procédez comme suit
curl -X GET \
https://sandbox-api.fedapay.com/v1/transactions/ID \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json'
$transaction = \FedaPay\Transaction::retrieve(ID);
if ($transaction->status == "approved") {
echo "Paiement effectué";
}
const transaction = await Transaction.retrieve(ID);
if (transaction.status == "approved") {
console.log("Paiement effectué");
}
Faire un paiement sans redirection
Il est possible de pouvoir faire des paiements sans rediriger l'utilisateur vers la page de paiement, par exemple, lorsque vous désirez garder l'utilisateur sur votre site ou application web sans changer son expérience. Dans ce cas, il faudra que vous implémentiez le formulaire de paiements vous meme dans votre application.
1- Envoyer un paiement mobile money sans redirection
Il faudra tout d'abord créer une transaction puis obtenir son token. Ensuite envoyer une requête de suivant l'une des méthodes de paiement suivantes:
mtn
: pour MTN Mobile Money Béninmoov
: pour Moov Béninmtn_ci
: pour MTN Mobile Money Côte d'Ivoiremoov_tg
: pour Moov Togo
Remplacez VOTRE_CLE_API_SECRETE par la clé API secrète de votre compte sandbox ou live. Si vous utilisez votre compte live, vous devez remplacer le lien par https://api.fedapay.com/v1/transactions/ID
Remplacez METHODE_PAIEMENT par l'une des méthodes de paiement cités plus haut.
curl -X POST \
https://sandbox-api.fedapay.com/v1/METHODE_PAIEMENT \
-H 'Authorization: Bearer VOTRE_CLE_API_SECRETE' \
-H 'Content-Type: application/json'
-d '{
"token" : "TOKEN_DE_PAIEMENT"
}'
Remplacez METHODE_PAIEMENT par l'une des méthodes de paiement cités plus haut.
$transaction = \FedaPay\Transaction::create(...);
$token = $transaction->generateToken()->token;
$mode = 'METHODE_PAIEMENT'; // 'mtn', 'moov', 'mtn_ci', 'moov_tg'
$transaction->sendNowWithToken($mode, $token);
Remplacez METHODE_PAIEMENT par l'une des méthodes de paiement cités plus haut.
const transaction = await Transaction.create(...);
const token = transaction.generateToken().token;
const mode = 'METHODE_PAIEMENT'; // 'mtn', 'moov', 'mtn_ci', 'moov_tg'
await transaction.sendNowWithToken(mode, token);
2- Récupérer le statut de la transaction
Si vous envoyer un paiement sans redirectement, il y a deux manières de récupérer le statut d'une transaction étant donnée que celle-ci est payée quelques secondes plus tard après l'envoie de la requête de paiement.
- Envoyer une requête pour récupérer les détails de la transaction. Confère étape 5.
- Implémenter les webhooks pour recevoir la notification de paiement. Confère la section webhooks.
Cycle de vie des transactions
Lorsque vous créez une transaction, elle passe par différents états ou statuts : c’est le cycle de vie des
transactions.
Ces statuts sont :
pending
: En attenteapproved
: Approuvéedeclined
: Déclinéecanceled
: Annuléerefunded
: Rembourséetransferred
: Transférée
Au départ, dès que vous créez votre transaction, elle est en En attente
.
C’est le statut par défaut.
La transaction passera à Approuvée
lorsque le paiement aura été bien effectué
par votre client.
Elle passe à Déclinée
si au moment d’effectuer le paiement,
votre client n’a pas assez d’avoirs sur le compte qu’il a choisi pour régler
cette transaction ou qu’il a un problème avec ce compte.
Elle est Annulée
lorsque que votre client au moment d’effectuer le paiement,
annule délibérément ou involontairement le processus.
Remboursée
lorsque le paiement effectué par votre client lui a été reversé.
Transférée
lorsque le montant d’une transaction a été envoyé par FedaPay sur la balance de
votre compte marchand.
Seules les transactions qui ont été approuvées sont transférées vers votre balance.
Vous pourrez consulter le statut de chacune de vos transactions toujours au niveau de votre tableau de bord FedaPay dans le menu Transactions pour suivre leur évolution.
Pour des raisons de sécurité, nous vous recommandons cependant d’adresser une nouvelle requête avec l’identifiant (ID) d’une transaction pour avoir son statut réel.