@finalse/sdk-node NPM

Sdk to access Finalse Cloud platform in Javascript Typescript for NodeJS based environment.

Install

yarn add @finalse/sdk-node or npm install @finalse/sdk-node

Usage

Initialisation

import {Auth, FinalseClient} from '@finalse/sdk-node';

// Initialize the FinalseClient with AuthAccess Token and SecretKey
const finalse = FinalseClient(Auth({token: '...', secretKey: '********'}));

or alternatively

const sdk = require('@finalse/sdk-node');

// Initialize the FinalseClient with AuthAccess Token and SecretKey
const finalse = sdk.FinalseClient(sdk.Auth({token: '...', secretKey: '********'}));

FundRequest

Request Funds to someone: Use this to ask someone to pay you Money.

Creating FundRequest: The Basics

// Create the Fund Request object
const fundRequestPromise = finalse.fundRequest.create({
  h1: 'Concert Zouglou - Ticket VIP',
  amount: {
    value: '100000',
    currency: 'XOF',
  },
});

fundRequestPromise.then(fundRequest => {
  // Having the FundRequest Object, you can now have the Secure Pay
  // payment link. Redirect the user on the securePayLink and you're done.
  const securePayLink = fundRequest.securePay.link;
  console.log(securePayLink);

  // Alternatively, you can let the User scan the QrCode et voilà
  // Let the User scan the QrCode et voilà
  const securePayQrCodeImageSrc = fundRequest.securePay.qrCode.src;
  console.log(securePayQrCodeImageSrc);
});

Congratulation :tada: :tada:

Here is the result if you visit the page of securePayLink. NB: Once payment completed, a Transaction will be created

Creating FundRequest: Going Further

// You can indicate on creation the following attributes
const fundRequestPromise = finalse.fundRequest.create({
  h1: {               // h1 is basically the answer to the question 'Why 
    fr: 'Ticket VIP', // are you requesting that money ? 
    en: 'VIP Ticket', // 'h1's type is: string | {fr: string, en: string}
  },                  // When h1 is string, then the default language of
                      // this FundRequest is set to your account language
                      // 
                      // When h1 is not a string, this means that you want
                      // to display a message depending of the language 
                      // of your customer. If the customer speaks english
                      // or is in an english speaking country the 'h1.en'
                      // will be displayed to him.
                      // 
                      // Note: if your home language is fr, it is possible 
                      //       to specify {en: 'Vip Ticket'}
                      //       and not specify french language to avoid the
                      //       h1 be tokenized and stored in your 
                      //       default language.
  amount: {
    value: '100 000', // Our platform accepts spaces in number to let you 
    currency: 'XOF',  // visually verify numbers you submit
  },

  expire: 'after 5m', // Should the FundRequest expires after certain time?
                      // This is useful if your are creating this Fund 
                      // Request to make reservations or promotional offers.
                      // Syntax: '<after><space><$number><$timeUnit>'
                      //         '<on><space><$iso8601Datetime>'
                      //         'never'  (default value)
                      // Examples:
                      // '<after><space><number><time unit>' : 'after 5m'
                      //                                       'after 90s' 
                      //                                       'after 1d'
                      //                                       'after 1w'
                      //                                       'after 1M'
                      // '<on><space><iso8601Datetime>'  : 'on 2023-01-01T01:00Z'
                      //
                      // Notes: The value 'never' has the same effect as if 
                      //        the field 'expire' has been omitted.

  destination: 'main',// What is the destination of the funds ? or What 
                      // is the wallet on which the money should Go when
                      // the customer will pay you ?
                      // With Finalse Pay, you are allowed to have multiple
                      // wallets (Wallets are some kind of sub accounts with
                      // their owns transactions history: You can have one 
                      // Wallet per client or one wallet per Business Unit
                      // or whatever you want to)
                      // So here you can specify which wallet should be 
                      // used to receive this FundRequest. 
                      // Allowed values are :
                      //     'Main' : (case insensitive, default value) Use
                      //              your main wallet
                      //     '$walletId' : Use the wallet identified by its ID

  fees: {             // Who pays the Fees ? Allowed values are the 
    payer: 'Me',      // following (case insensitive) :       
  },                  //    'Sender': The Money Sender pays the fees. Here
                      //              we are asking for money so the 
                      //              CounterPart is the Sender
                      //    'Receiver': The Money Receiver pays the fees.
                      //                Here we are asking for money so 
                      //                we are the Money Receiver.     
                      //    'Me': (default value) Not need to explain :-)
                      //    'CounterPart': The transaction Counter Part 
                      //                   (the person I am doing the 
                      //                   transaction with) pays the fees.
                      //                   (aka 'Not Me' no matter if I am
                      //                   the Sender or the Receiver)

  securePay: {
    onSuccess: {
      redirectUserTo: 'https://www.sefigroup.net/order/1234/payment-success',
      // We will redirect customer on success with the following query string:
      //    - spid: (SecurePayId) The value will be the Fund Request Id
      //    - fid: (ForeignId) The value will be the ForeignId if submitted
      //    - txid: (TransactionId) The id of the created Transaction
      //    - ty: the value 'FundRequest'
    },
    onFailure: {
      redirectUserTo: 'https://www.sefigroup.net/order/1234/payment-failure?timestamp=19000',
      // We will redirect customer on success with query string:
      //    - spid: (SecurePayId) The value will be the Fund Request Id
      //    - fid: (ForeignId) The value will be the ForeignId if submitted
      //    - ty: the value 'FundRequest'
    },
  },

  description: '...',   // Additional description about this FundRequest. 
                        // (Won't be visible by the counter part)

  foreignId: '...',     // Custom Identifier you want to add to ths Fund 
                        // request. It should be uniq amount all 
                        // FundRequests.
                        // This let you fetch a FundRequest by foreignId
                        // having the value you submit.
                        // Notes: This value Won't be visible by the counter
                        //        part You will see below how to fetch a 
                        //        FundRequest by its ForeignId.

  foreignData: '...',   // Custom Data you would like to attach to this 
                        // FundRequest. It can be a Json value or any 
                        // string as long as it does not exceed 1024 chars.
                        // (Won't be visible by the counter part)
});

Get FundRequest

const fundRequestPromise = finalse.fundRequest.get('<fund request id | fund request foreign id>');
// It possible to get a FundRequest by its ForeignId : The one you've supplied on
// FundRequest creation.

List FundRequest: The Basic

// List all Fund requests returning most recent firsts.
// The returned results will be paginated and the way to navigate between page
// will be explained later.
const fundRequestCollectionPromise = finalse.fundRequest.list();

List FundRequest: Going Further

// Introducing ListForm
// The Previous request is equivalent to the following
import {ListForm} from '@finalse/sdk-node';
const fundRequestCollectionPromise = finalse.fundRequest.list({
  orderBy: 'createdTime:DESC',
  limit: 50,
});

Updating FundRequest

Updating is done in a controlled manner to reduce errors. Remember, A good API should be easy to use and hard to misuse. Because of that, we have created an update form that have all possible updates on per fields basis. For example, the field description in a FundRequest is updatable and removable. Hence you will have a mean either to remove it or to update it.

import {UpdateFundRequestForm} from '@finalse/sdk-node';

// Update a Fund Request by Removing existing Description
const fundRequestPromise = finalse.fundRequest.update({
  id: '<fund request id | fund request foreign id>',
  remove: ['description'],
});

// Update a Fund Request by Setting a New Description
const fundRequestPromise = finalse.fundRequest.update({
  id: '<fund request id | fund request foreign id>',
  set: {
    description: 'New Description',
  },
});

// So if you want to remove both fields 'description' and 'foreignData'
const fundRequestPromise = finalse.fundRequest.update({
  id: '<fund request id | fund request foreign id>',
  remove: ['description', 'foreignData'],
});

// So if you want to set the field 'description' and remove the field 'foreignData'
const fundRequestPromise = finalse.fundRequest.update({
  id: '<fund request id | fund request foreign id>',
  remove: ['foreignData'],
  set: {
    description: 'New Description',
  },
});