Integration with Custom UI

Context  

You're developing a web application, website or a mobile application and would like to to add a payment method. What's more, you'd like your users to be able to pay with your own UI.

Goal to Achieve  

1 - Your user has to pay. You create a form to collect payment data.
2 - Once the payment data has been collected, your application asks your server to initiate a payment with the FPay SDK.
3 - Your user will receive a request to validate the payment.
4 - Your application periodically checks whether the payment has been successful or not with the FPay SDK.
You can trigger delivery of the product that has just been paid, or you can inform the user of the payment failure.
5 - Et voilà

Pre Requisites  

Initialization  

npm install @finalse/sdk-node

yarn add @finalse/sdk-node

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

Implementation  

To receive money from the user, you need to create a Deposit  object for let the user to deposit into your FPay account.

1 - Collect payment data

Your UI needs to collect the following data

"<Amount>"

The total amount to be sent by the user.

"<Country>"

This is the ISO 3166 Alpha 2 code of the country where your Mobile Money account is located. account is located. For the moment, the only possible value is CI 

"<Provider>"

This is your user's Money provider. Possible values are: OrangeMoney   MtnMoney    MoovMoney   or  FPay .

"<MobileNumber>"

This is the user's telephone number. can be in local 10-digit format or in international format with area code +255 for Côte d'Ivoire

2 - Initiate payment with FPay's SDK

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

depositPromise.then(deposit => {

    // To validate this payment, your user must perform an action.  
    // The action to be executed must be returned to your UI. Here's how to access it  
    const mfa = deposit.mfa.asSecretCodeRequired(); 
    if(mfa != undefined){
        console.log(mfa.requiredAction); 
    }
});

3 - Check whether the payment was a success or an error with the FPay SDK  

//  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à

Going Further  

Multi Language Support  

When creating the Deposit object, if you specify the h1  field , the value entered will be displayed to your user as the reason for payment. It is possible to specify a value in English and a value in French.

How its works?

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  

Whenever money is added to your account, the funds collected will be deposited in your main  Wallet  by default. Because you can create several additional  Wallet , you can also choose where the funds arrives once the user has paid.
So, you can have one  Wallet  for your savings, or one Wallet per store if you have several stores, and choose where the funds received will go.

How it works ?

To specify the destination of the funds, you need the MARS of the  Wallet, available vie the mars.alpha field.
For example, if the Wallet's MARS is "CI FPay W09POT", then you would enter the following code:

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"
        }
    });

Fees Payer  

By default, transactions fees are paid by your customer. You can specify specify who pays them to change this default behavior according to the situations you need to manage.
For example, suppose you want to make a cash inflow to your FPay account in the amount of ₣ 10,000 The question you need to ask yourself is How much money my user should pay ? If the answer is ₣ 10,000, then then you pay the fees.
You can also ask the question the other way around: How much money should arrive on my FPay account? If the answer is ₣ 10,000, then it's your user who will pay the fees.

To specify who pays the fees, 4 values are possible:

"Me"

You pay the fees

"CounterPart"

Your user (the counter part) pays the fees

"Sender"

Whoever sends the money pays the fees, whether it's you or your user

"Receiver"

Whoever receives the money pays the costs, whether it's you or your user.

Code example

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  

When creating the Deposit object, you can attach your own internal ID. In this way, When retrieving the Deposit object, you will be able to use your own  id  instead of the one generated by FPay. The ID you submit must be unique for each object type.
One of the advantages of submitting your own unique identifier is that you can carry outidempotent queries. In fact, if your submitted foreignId is unique, then you're protected against duplications due to networks, for example, and you'll be able to control retries without worrying about repeating the same operation several times.

For creation

const depositPromise = 
    fPay.deposit.initiate({
        foreignId: "<my internal id>",
        source: {
            _type: "Single",
            account: {
                country: "CI",
                identifier: "+2250100000000",
                providerKey: "MoovMoney"
            }
        }
    });

At retrieval

With the previous code, you now have the right to do the following code to retrieve Deposit object.

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

Foreign Data  

When creating Deposit object, you can add your own data to tag the object you've created.
For example, you can add the following data:

•   {"myKey": 19, "myOtherKey": "myOtherValue"}
•   <xml><myKey>myValue</myKey></xml>
•   myValue1, myValue2, myValue3
•  Any string you like, as long as it doesn't exceed 255 characters.

On creation

const depositPromise = 
    fPay.deposit.initiate({
        foreignData: "<xml><myKey>myValue</myKey></xml>",
        source: {
            _type: "Single",
            account: {
                country: "CI",
                identifier: "+2250100000000",
                providerKey: "MoovMoney"
            }
        }
    });

When retrieving

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>" 
});