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 transaction
  • amount : définir le montant de la transaction. Ce montant doit toujours être un nombre entier
  • currency : préciser la devise à utiliser pour 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.

  • callback_url : le lien de retour
  • customer : préciser le client avec lequel doit se faire la transaction

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_PRIVEE' \
-H 'Content-Type: application/json' \
-d '{
      "description" : "Transaction for john.doe@example.com",
      "amount" : 2000,
      "currency" : {"iso" : "XOF"},
      "callback_url" : "https://maplateforme.com/callback",
      "customer" : {
          "firstname" : "John",
          "lastname" : "Doe",
          "email" : "john.doe@example.com",
          "phone_number" : {
              "number" : "+22997808080",
              "country" : "bj"
          }
        }
    }'
/* Remplacez VOTRE_CLE_API par votre véritable clé API */
\FedaPay\FedaPay::setApiKey("VOTRE_CLE_API_PRIVEE");

/* 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 john.doe@example.com",
  "amount" => 2000,
  "currency" => ["iso" => "XOF"],
  "callback_url" => "https://maplateforme.com/callback",
  "customer" => [
      "firstname" => "John",
      "lastname" => "Doe",
      "email" => "john.doe@example.com",
      "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_PRIVEE");

/* 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: 'john.doe@example.com',
      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_PRIVEE' \
-H 'Content-Type: application/json' \
-d '{
      "description" : "Transaction for john.doe@example.com",
      "amount" : 2000,
      "currency" : {"iso" : "XOF"},
      "callback_url" : "https://maplateforme.com/callback",
      "customer" : {
          "email" : "john.doe@example.com",
        }
    }'
/* Remplacez VOTRE_CLE_API par votre véritable clé API */
\FedaPay\FedaPay::setApiKey("VOTRE_CLE_API_PRIVEE");

/* 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 john.doe@example.com",
  "amount" => 2000,
  "currency" => ["iso" => "XOF"],
  "callback_url" => "https://maplateforme.com/callback",
  "customer" => [
    "email" => "john.doe@example.com" /* ou "id" => 105 */
  ]
));
const { FedaPay, Transaction } = require('fedapay')

/* Remplacez VOTRE_CLE_API par votre véritable clé API */
FedaPay.setApiKey("VOTRE_CLE_API_PRIVEE");

/* 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: 'john.doe@example.com' /* 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_PRIVEE' \
-H 'Content-Type: application/json'
$transaction = \FedaPay\Transaction::create(array(...))
$token = $transaction->generateToken();
return redirect($token->url);
const transaction = await Transaction.create({...})
const token = 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
Le callback_url ou lien de retour, vous permet de rediriger automatiquement votre client vers une page précise de votre choix, une fois qu'il arrive au bout du processus de règlement d'une transaction.
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.
Exemples
  • 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.

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_PRIVEE' \
-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é");
}

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 attente
  • approved: Approuvée
  • declined: Déclinée
  • canceled: Annulée
  • refunded: Remboursée
  • transferred: 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.