Integration with FPay 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 the FPay UI.

Next, please select the type of client application you are developing

You are developing a Web Site

Goal to Achieve  

1 - Your user has to pay. Let's imagine he's on your site in front of the “pay” button. The user clicks to pay.
2 - Following the click, your server retrieves a payment url using the FPay SDK, then redirects the user to the retrieved url.
3 - The user pays, and at the end of the payment FPay redirects the user to your website.
4 - Your server checks whether the payment was a success or a failure using the FPay SDK.
You can trigger delivery of the product that has just been paid for, or you can inform the user that payment has failed.
5 - Et voilà

Routes  

Assume you've defined the following routes. Of course, you can name them anything you like, but for the purposes of this documentation, let's consider the following names for a moment:

We will explain how to interact with the FPay SDK and do the following 2 routes :

• 1   /pay
  Get a payment url with the FPay SDK
  
• 2   /pay-completed/:payId
  Once payment completed Check whether the payment was a success or an error with the FPay SDK
  

Pre Requisites  

Initialization  

npm install @finalse/sdk-node

yarn add @finalse/sdk-node

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

Implementation  

For the user to make a payment, we'll create a FundRequest object to aks him money. The object FundRequest thus created will contain a url to which we should redirect the user to.

1 - /pay
To implement this route, we will get a payment url with the FPay SDK. Let's do the following things :

//  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: "Shopping cart payment #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
Once payment completed Check whether the payment was a success or an error with the FPay SDK  

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

Going Further  

Expires  

When creating the FundRequest object , you can specify the time on which the fund request expires.
This can be useful, for example, if you're making promotional offers and the payment of the user is about a limited reduced price.
It can also be useful if you're asking the user to pay for a reservation: You reserve the item for sale until the user has paid, after expire time, if the user has not paid yet, the item becomes available to another potential user.

General Format

Some examples of allowed values

"after 15m"

The funds request will expire 15 minutes after creation

"after 90s"

The funds request will expire 90 seconds after creation

"after 1h"

The created object will expire 1 hour after creation

"after 2d"

The created object will expire 2 days after creation

"after 1w"

The created object will expire 1 week after creation

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

The created object will expire on May 19, 2028 at 01:13 GMT. The 'Z' at the end stands for GMT and this format is from ISO 8601.

"on 2028-05-19"

The created object will expire on May 19, 2028 at 00:00 GMT

"on 15:30"

The created object will expire at 15:30 GMT on the day of its creation.

How its works ?

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

Multi Language Support  

When creating the FundRequest 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.In this way, the user will be able to change language, and the default language displayed will be that of his browser: If you're selling to an French-speaking user, the text entered in French will be displayed to him automatically.

How its works?

const fundRequestPromise = 
    fPay.fundRequest.create({
        h1: {
            fr: "Paiement panier #12",
            en: "Shopping cart payment #12"
        },
        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 fundRequestPromise = 
    fPay.fundRequest.create({
        destination: "CI FPay W09POT",
        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 fundRequestPromise = 
    fPay.fundRequest.create({
        fees: {
            payer: "CounterPart"
        },
        amount: {
            currency: "XOF",
            value: "10_000"
        }
    });

Foreign ID  

When creating the FundRequest object, you can attach your own internal ID. In this way, When retrieving the FundRequest 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 fundRequestPromise = 
    fPay.fundRequest.create({
        foreignId: "<my internal id>"
    });

At retrieval

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

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

Foreign Data  

When creating FundRequest 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 fundRequestPromise = 
    fPay.fundRequest.create({
        foreignData: "<xml><myKey>myValue</myKey></xml>"
    });

When retrieving

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