Intégration avec le UI de FPay

Contexte  

Vous développez une application web, un site web ou une application mobile et vous souhaitez y ajouter un moyen de paiement. De plus, vous voudriez que le paiement de vos utilisateurs se fasse avec le UI de FPay.

Pour la suite, veuillez choisir le type d'application cliente que vous developpez

Vous développez un Site Web

Résultat à Obtenir  

1 - Votre utilisateur doit payer. Imaginons qu'il soit sur votre site web devant le bouton "payer". L'utilisateur clique pour payer.
2 - Suite au click, votre serveur recupère une url de paiement avec le SDK de FPay puis redirige l'utilisateur vers l'url recupérée.
3 - L'utilisateur paye et à la fin du paiement, FPay redirige l'utilisateur vers votre site web.
4 - Votre serveur vérifie que le paiement a été un success ou un échec avec le SDK de FPay.
Vous pouvez déclencher la livraison du produit qui vient d'être payé où alors informer l'utilisateur de l'echec du paiement.
5 - Et voilà

Routes  

Supposons que vous ayez défini les routes suivantes. Bien sur, vous pouvez les nommer comme vous voudrez mais pour le besoin de cette documentation considérons un instant les noms de routes suivants :

Nous allons vous expliquer comment interagir avec le SDK de FPay et implementer les 2 routes suivantes :

• 1   /pay
  Recupérer une url de paiement avec le SDK de FPay
  
• 2   /pay-completed/:payId
  Vérifier que le paiement a été un succès ou une erreur avec le SDK de FPay
  

Pré Requis  

Initialisation  

npm install @finalse/sdk-node

yarn add @finalse/sdk-node

const fPay = sdk.FPayClient(sdk.Auth({token: '<token>', secretKey: '<secretKey>' }));

Implémentation  

Pour que l'utilisateur fasse un paiement, nous allons créer un objet FundRequest pour lui demander des fonds. L'objet FundRequest ainsi créé contiendra une url vers laquelle nous devons rediriger l'utilisateur.

1 - /pay
Pour Implémenter cette route, nous allons récupérer une url de paiement avec le SDK de FPay. Effectuons les actions suivantes :

//  Generate an ID for the payment. The 'payId' value seen above
//  It's should be uniq and Random

//  ... <generate pay id code here>

//  After you have generated the payId, create the FundRequest object

const fundRequestPromise = 
    fPay.fundRequest.create({
        amount: {
            currency: "XOF",
            value: "10_000"
        },
        h1: "Paiement panier #12",
        onFailure: {
            redirectUserTo: "https://your-server.com/pay-completed/:payId"
        },
        onSuccess: {
            redirectUserTo: "https://your-server.com/pay-completed/:payId"
        }
    });

//  Please save the .id of the returned FundRequest along with the 'payId'
//  so that it will be possible to Get the FundRequest id by the 'payId'
const fundRequestId = fundRequest.id;

//  ... <save payId, fundRequestId code here>

const paymentUrl = fundRequest.securePay.link;
//  Now, you can redirect the user to the value of  paymentUrl

//  ... <redirect user to paymentUrl code here>

2 - /pay-completed/:payId
Pour implémenter cette deuxième route qui sera appelée lorsque le paiement sera terminé, nous allons vérifier que le paiement a été un succès ou une erreur avec le SDK de FPay  

//  With the submitted payId,Get the previously saved id of the FundRequest 
const fundRequestPromise = fPay.fundRequest.get("<fundRequest.id>");

fundRequestPromise.then(fundRequest => {

    //  Inspect the 'status' of the FundRequest and if successful, do the stuff...
    const isCompleted = fundRequest.status.isSuccessful() || fundRequest.status.isFailure();
});

3 - Et voilà

Aller plus loin  

Expire  

Il est possible de spécifier lors de la création de l'objet FundRequest   une date à laquelle l'expiration aura lieu.
Ceci peut être utile par exemple si vous faites des offres promotionnelles et que le paiement que s'apprête à faire l'utilisateur correspond à une offre limitée.
Cela peut être également utile si vous demandez à l'utilisateur un paiement pour une réservation : Vous réservez l'objet à vendre le temps que l'utilisateur fasse son paiement. Passé le délai d'expiration, si l'utilisateur n'a pas éffectué de paiement, cet objet re-devient disponible pour un autre client potentiel.

Format général

Quelques exemples de valeurs autorisées

"after 15m"

L'objet créé expirera 15 minutes après sa création

"after 90s"

L'objet créé expirera 90 secondes après sa création

"after 1h"

L'objet créé expirera 1 heure après sa création

"after 2d"

L'objet créé expirera 2 jours après sa création

"after 1w"

L'objet créé expirera 1 semaine après sa création

"on 2028-05-19T01:13Z"

L'objet créé expirera le 19 Mai 2028 à 01h13 GMT. Le 'Z' à la fin signifie GMT et ce format est issue de la norme ISO 8601.

"on 2028-05-19"

L'objet créé expirera le 19 Mai 2028 à 00h00 GMT

"on 15:30"

L'objet créé expirera le jour de sa création à 15h30 GMT

Comment ça marche ?

const fundRequestPromise = 
    fPay.fundRequest.create({
        amount: {
            currency: "XOF",
            value: "10_000"
        },
        expire: "after 45m"
    });

Support Multi Language  

Lors de la création de l'objet FundRequest , si vous spécifiez le champ h1 , la valeur saisie sera affichée à votre utilisateur comme motif de la transaction. Il est possible de spécifier une valeur en Français et une valeur en Anglais lors de la création de l'objet FundRequest .Ainsi, L'utilisateur aura la possibilité de changer de langue et la langue par defaut affichée sera celle de son navigateur: Si vous vendez à un client anglophone, le texte saisi en Anglais s'affichera automatiquement.

Comment ça marche ?

const fundRequestPromise = 
    fPay.fundRequest.create({
        h1: {
            fr: "Paiement panier #12",
            en: "Shopping cart payment #12"
        },
        amount: {
            currency: "XOF",
            value: "10_000"
        }
    });

Destination  

Lors de toute entrée d'argent sur votre compte, les fonds recupérés seront déposés sur votre  Wallet  principal par défaut. Parce qu'il vous est possible de créer plusieurs  Wallet  additionnels, il vous est également possible choisir la destination des fonds une fois que l'utilisateur aura payé.
Ainsi, vous pouvez posséder un  Wallet  pour votre épargne ou bien un  Wallet  par magasin si vous avez plusieurs magasins et choisir où iront les fonds reçus.

Comment ça marche ?

Pour spécifier la destination des fonds, il vous faut le MARS du  Wallet , accessible via le champ mars.alpha
Par exemple si le MARS du Wallet  est "CI FPay W09POT", alors vous devriez entrer le code suivant :

const fundRequestPromise = 
    fPay.fundRequest.create({
        destination: "CI FPay W09POT",
        amount: {
            currency: "XOF",
            value: "10_000"
        }
    });

Qui paye les frais ?  

Par défaut, les frais liées aux transactions sont payés par votre client. Il vous est possible de spécifier qui les paye pour changer ce comportement par défaut suivant les situations que vous aurez à gérer.
Par exemple, supposons que vous voulez éffectuer une entrée d'argent sur votre compte FPay d'un montant de 10 000 ₣. La question que vous devez vous poser est la suivante Combien doit sortir du compte de mon utilisateur ? si la réponse est 10 000 ₣, alors c'est vous qui payez les frais.
Vous pouvez également vous poser la question dans l'autre sens : Combien doit arriver sur mon compte FPay ? si la réponse est 10 000 ₣, alors c'est votre utilisateur qui payera les frais.

Pour spécifier qui paye les frais, 4 Valeurs sont possibles :

"Me"

Vous prenez en charge les frais

"CounterPart"

Votre utilisateur (la contre partie) paye les frais

"Sender"

Celui qui envoie de l'argent paye les frais que ce soit vous ou votre utilisateur

"Receiver"

Celui qui reçoit de l'argent prends en charge les frais que ce soit vous ou votre utilisateur

Exemple de code

const fundRequestPromise = 
    fPay.fundRequest.create({
        fees: {
            payer: "CounterPart"
        },
        amount: {
            currency: "XOF",
            value: "10_000"
        }
    });

Foreign ID  

Lors de la création de l'objet FundRequest , il vous est possible d'attacher votre propre ID interne à votre système. Ainsi, plus tard, lors de la recupération de l'objet FundRequest , vous pourrez utiliser votre propre ID au lieu de l' id  qui sera généré par FPay. L'ID que vous soumettez doit être unique pour chaque type d'objet.
Un des avantages de soumette votre propre identifiant unique est de pouvoir éffectuer des requêtes idempotentes. En effet, si votre foreignId soumis est unique, alors vous êtes protegé contre les duplications dues au réseaux par exemple et vous contrôlerez les retry sans trembler ni risquer de répéter plusieurs fois la même opération.

Pour la création

const fundRequestPromise = 
    fPay.fundRequest.create({
        foreignId: "<my internal id>"
    });

Pour la récupération

Avec le code précédent, vous avez désormais le droit de faire le code suivant lors de la recupérationde l'objet FundRequest .

const fundRequestPromise = fPay.fundRequest.get("<my internal id>");

Foreign Data  

Lors de la création de l'objet FundRequest , il vous est possible d'ajouter des données qui vous sont propres et qui vous permettront de "tagguer" l'objet créé.
Vous pourrez par exemple ajouter les données suivantes :

•   {"myKey": 19, "myOtherKey": "myOtherValue"}
•   <xml><myKey>myValue</myKey></xml>
•   myValue1, myValue2, myValue3
•  Toute chaine de caractères que vous souhaitez à partir du moment celle ci n'excède pas 255 caractères.

Lors de la création

const fundRequestPromise = 
    fPay.fundRequest.create({
        foreignData: "<xml><myKey>myValue</myKey></xml>"
    });

Lors de toute récupération

const fundRequestPromise = fPay.fundRequest.get("<fundRequest.id | foreignId>");

fundRequestPromise.then(fundRequest => {
   // Inspect the 'foreignData' field of the FundRequest ... 
   const xmlData = fundRequest.foreignData;
   // xmlData = "<xml><myKey>myValue</myKey></xml>" 
});