Intégration avec un UI personalisé

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 entièrement avec votre propre UI.

Resultat à Obtenir  

1 - Votre utilisateur doit payer. Vous faites un formulaire pour collecter les données de paiement.
2 - Une fois que les données de paiement ont été collectées, votre application demande à votre serveur d'initier un paiement avec le SDK de FPay.
3 - Votre utilisateur va recevoir une demande l'invitant à valider le paiement ainsi initié.
4 - Votre application vérifie périodiquement 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à

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 recevoir l'argent de l'utilisateur, vous devez créer un objet Deposit  pour qu'il fasse un dépôt sur votre compte FPay.

1 - Collecter les données de paiement

Votre UI doit collecter les données suivantes :

"<Amount>"

Le montant total que l'utilisateur doit vous envoyer.

"<Country>"

Il s'agit du code ISO 3166 Alpha 2 du pays où se trouve le compte Mobile Money de votre utilisateur. Pour l'instant, la seule valeur possible est CI 

"<Provider>"

Il s'agit du fournisseur du compte Money de votre utilisateur Les valeurs possibles sont: OrangeMoney   MtnMoney  MoovMoney   ou  FPay .

"<MobileNumber>"

Il s'agit du numéro de téléphone de l'utilisateur qui peut etre au format local de 10 chiffres ou au format international avec l'indicatif +255 pour la Côte d'Ivoire

2 - Initier le paiement avec le SDK de FPay

const depositPromise = 
    fPay.deposit.initiate({
        amount: {
            currency: "XOF",
            value: "<Amount>"
        },
        source: {
            _type: "Single",
            account: {
                country: "<Country>",
                identifier: "<MobileNumber>",
                providerKey: "<Provider>"
            }
        },
        h1: "Paiement panier #12"
    });

depositPromise.then(deposit => {

    // Pour valider ce paiement, votre utilisateur doit exécuter une action. 
    // L'action à exécuter doit être retournée à votre UI. Voilà comment y accéder 
    const mfa = deposit.mfa.asSecretCodeRequired(); 
    if(mfa != undefined){
        console.log(mfa.requiredAction); 
    }
});

3 - Vérifier périodiquement que le paiement a été un succès ou une erreur avec le SDK de FPay  

//  Get the previously saved id of the Deposit 
const depositPromise = fPay.deposit.get("<deposit.id>");

depositPromise.then(deposit => {

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

3 - Et voilà

Aller plus loin  

Support Multi Language  

Lors de la création de l'objet Deposit , 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 Deposit .

Comment ça marche ?

const depositPromise = 
    fPay.deposit.initiate({
        h1: {
            fr: "Paiement panier #12",
            en: "Shopping cart payment #12"
        },
        source: {
            _type: "Single",
            account: {
                country: "CI",
                identifier: "+2250100000000",
                providerKey: "MoovMoney"
            }
        },
        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 depositPromise = 
    fPay.deposit.initiate({
        destination: "CI FPay W09POT",
        source: {
            _type: "Single",
            account: {
                country: "CI",
                identifier: "+2250100000000",
                providerKey: "MoovMoney"
            }
        },
        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 depositPromise = 
    fPay.deposit.initiate({
        fees: {
            payer: "CounterPart"
        },
        source: {
            _type: "Single",
            account: {
                country: "CI",
                identifier: "+2250100000000",
                providerKey: "MoovMoney"
            }
        },
        amount: {
            currency: "XOF",
            value: "10_000"
        }
    });

Foreign ID  

Lors de la création de l'objet Deposit , il vous est possible d'attacher votre propre ID interne à votre système. Ainsi, plus tard, lors de la recupération de l'objet Deposit , 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 depositPromise = 
    fPay.deposit.initiate({
        foreignId: "<my internal id>",
        source: {
            _type: "Single",
            account: {
                country: "CI",
                identifier: "+2250100000000",
                providerKey: "MoovMoney"
            }
        }
    });

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 Deposit .

const depositPromise = fPay.deposit.get("<my internal id>");

Foreign Data  

Lors de la création de l'objet Deposit , 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 depositPromise = 
    fPay.deposit.initiate({
        foreignData: "<xml><myKey>myValue</myKey></xml>",
        source: {
            _type: "Single",
            account: {
                country: "CI",
                identifier: "+2250100000000",
                providerKey: "MoovMoney"
            }
        }
    });

Lors de toute récupération

const depositPromise = fPay.deposit.get("<deposit.id | foreignId>");

depositPromise.then(deposit => {
   // Inspect the 'foreignData' field of the Deposit ... 
   const xmlData = deposit.foreignData;
   // xmlData = "<xml><myKey>myValue</myKey></xml>" 
});