Libraries and SDKs

Learn about the different libraries and SDKs Finix has available to use.


Finix is actively working on making libraries and SDKs available for the most popular languages.

We've recently launched Finix's Python, Java, and Node.js libraries and are actively iterating on them to make improvements.

If you're interested in using our libraries and providing feedback, please reach out to your Finix point of contact. Finix is super eager to share what our community comes up with and develops!

Finix Python Library

This is the official Finix Python library. If you plan on using the Finix Python library or have any feedback please reach out to your Finix point of contact.

Prerequisites

  • Python 3.6 or later

Installing the Python Library

  • Installing from PyPl:
    Copy
    Copied
    pip install --upgrade finix
  • Installing from source:
    Copy
    Copied
    python setup.py install

Using the Library

Initialization

Copy
Copied
import finix
from finix.configuration import Environment, Configuration
from finix.models import *        
# finix.models is intended for wildcard import, feel safe to import all predefined models at once

config = Configuration(
    username = 'ENTER_YOUR_USERNAME',
    password = 'ENTER_YOUR_PASSWORD',
    environment = Environment.SANDBOX
)

client = finix.FinixClient(config)

Examples

Creating a Transfer

Copy
Copied
request = CreateTransferRequest(
    merchant='MUeDVrf2ahuKc9Eg5TeZugvs',
    currency = Currency("USD"),
    amount = 12345,
    source = 'PIe2YvpcjvoVJ6PzoRPBK137',
    tags = Tags(
        category = 'sale'
    )
)

transfer = client.transfers.create(create_transfer_request=request)

List Payment Instruments

Copy
Copied
# fetch 5 payment instruments and print id of each
payment_instruments = client.payment_instruments.list(limit=5)
for single_instrument in payment_instruments:
    print(single_instrument.id)

# fetch the next 5 payment instruments and print type of the first one
next_five_instruments = payment_instruments.list_next()
print(next_five_instruments[0].type)

Catch Exceptions

Copy
Copied
try:
    client.payment_instruments.get('this_is_invalid_id')

except finix.ApiException as e:
    # print basic http information of the exception
    print(e.status)
    print(e.reason)
    print(e.headers)
    # print message of each error in the http response body
    for err in e.body:
        print (err.message)

Supported APIs

Finix Java Library

This is the official Finix Java library. If you plan on using the Finix Java library or have any feedback please reach out to your Finix point of contact.

Prerequisites

  • Java 1.8+
  • Your own Finix API Credentials
    • Our tests use the Finix API credentials from our public documentation, but you need your own credentials.

Maven

Add the following to your project's pom.xml:

Copy
Copied
<dependency>
  <groupId>com.finix</groupId>
  <artifactId>finix-java</artifactId>
  <version>0.0.1</version>
</dependency>

Gradle

Add the following to your project's build.gradle:

Copy
Copied
implementation 'com.finix:finix-java:0.0.1'

Using the Library

Initialization

Provide your Finix API username, password and the environment you're interacting with:

Copy
Copied
finixClient= new FinixClient("USsRhsHYZGBPnQw8CByJyEQW","8a14c2f9-d94b-4c72-8f5c-a62908e5b30e", Environment.SANDBOX);
// Set API Version
finixClient.addDefaultHeader("Finix-Version","2022-02-01");

Example

Here is an example of creating a Transfer using Finix's Java Library:

Copy
Copied
CreateTransferRequest createTransferRequest = CreateTransferRequest
    .builder()
        .source("PIe2YvpcjvoVJ6PzoRPBK137")
        .merchant("MUeDVrf2ahuKc9Eg5TeZugvs")
        .tags(Map.of("order_number", "21DFASJSAKAS"))
        .currency(Currency.USD)
        .amount(100L)
        .processor("DUMMY_V1")
    .build();
Transfer transfer = finixClient.Transfers.create(createTransferRequest);

Downloading Files

Our Instrument Updates API and Files API lets you download a file. These downloaded files are saved in Java's default generated temporary folder path.

You can specify your own folder path with the following:

Copy
Copied
finixClient.setTempFolderPath('/path/to/tempfolder')

Supported APIs

Finix Node.js Library

This is the official Finix Node.js library. If you plan on using the Finix Node.js library or have any feedback please reach out to your Finix point of contact.

Prerequisites

  • Node.js 16 or higher
  • TypeScript
  • Suggested: Your own API credentials.
    • Our tests use the API credentials from Finix's public documentation, however you need your own credentials to submit requests.

Installing the Node.js Library

  • Installing from NPM :
    Copy
    Copied
    npm install --save @finix-payments/finix

Using the Library

Initialization

Provide your Finix credentials (username and password) as well as the environment you're working with.

Copy
Copied
import {Client, Environment, Models} from '@finix-payments/finix';

const userName = 'USsRhsHYZGBPnQw8CByJyEQW';
const password = '8a14c2f9-d94b-4c72-8f5c-a62908e5b30e';

const client = new Client(userName, password, Environment.Sandbox);

Examples

Creating a Transfer

Copy
Copied
const createTransferRequest: Models.CreateTransferRequest = {
             currency: Models.Currency.Usd,
             merchant: "MUeDVrf2ahuKc9Eg5TeZugvs",
             tags: {
                 "test": "sale"
             },
             source: "PIe2YvpcjvoVJ6PzoRPBK137",
             amount: 662154,
         };
const transfer = await client.Transfers.create(saleRequest);

List Transfers

finixList is the return type of all functions that retrieve a list.

Here's an example of using finixList to retrieve a list of Transfers with and without query parameters.

Copy
Copied
// Retrieving list of all transfers 
const transfersList : Models.finixList<Models.Transfer> = await client.Transfers.list();

// Retrieving list of transfers with the following filters: 
// List limit: 2
// Amount less than 100
// Transfer type: Debits 
const transfersListWithFilter = await client.Transfers.list({
    limit: 2,
    amountLt: 100,
    type: "Debits"  
});

// Accessing transfers in the list and print out value
for (let currTransfer of transfersList){
        console.log(currTransfer);
}

// Get the size of the current list 
const transferListSize : number = transfersList.size;

// Get the page object that contains properties including offset/nextCursor, limit.
// Note: refer to the specific api to see if the page object associated is of type pageCursor or pageOffset
const page : Models.PageCursor = transfersList.page;

// Get the links 
const links : Models.ListLinks = transfersList.links;

// Check if there is more to list, value equals to False if end of list has been reached 
const hasMore : Boolean = transfersList.hasMore;

// Get the next list 
const nextTransfersList : Models.finixList<Models.Transfer> = await transfersList.listNext();

Uploading a File

Here's an example of uploading a dispute evidence file. Files are expected to be type fs.ReadStream.

Copy
Copied
import * as fs from 'fs';

const fileName : string = __dirname.concat("/test.png");
const fileObject: fs.ReadStream = fs.createReadStream(fileName);
const uploadedDisputeEvidence = await client.Disputes.createDisputeEvidence(disputeId, {
    file: fileObject});

Supported APIs

Finix PHP Library

This is the official Finix PHP library. If you plan on using the PHP library or have any feedback please reach out to your Finix point of contact.

Prerequisites

  • PHP 8.0 or higher
  • Suggested: Your own API credentials.
    • Our tests use the API credentials from Finix's public documentation, however you need your own credentials to submit requests.

Composer

Copy
Copied
composer require finix/php

Using the Library

Initialization

Provide your Finix credentials (username and password) as well as the environment you're working with.

Copy
Copied
use \Finix\Model as Model;
use \Finix\Environment;
use \Finix\FinixClient;

$username = "<USERNAME>";
$password = "<PASSWORD>";
$environment = Environment::SANDBOX;
$client = new FinixClient($username, $password, $environment);

Examples

Creating a Transfer

Copy
Copied
$transfersRequest = new Model\CreateTransferRequest(array(
        'source' => "PIe2YvpcjvoVJ6PzoRPBK137", 
        'merchant' => "MUeDVrf2ahuKc9Eg5TeZugvs", 
        'tags' => array('order_number' => "21DFASJSAKAS"), 
        'currency' => Model\Currency::USD, 
        'amount' => 100, 
        'processor' => "DUMMY_V1"
));

$transfer = $client->transfers->create($transfersRequest);

List Transfers

finixList is the return type of all functions that retrieve a list.

Here's an example of using finixList to retrieve a list of Transfers with and without query parameters.

Copy
Copied
// Retrieving list of all transfers 
$transfersList = $client->transfers->list(array());

// Retrieving list of transfers with the following filters: 
// List limit: 2
// Amount less than 100
// Transfer type: Debits 
$transfersListWithFilter = $client->transfers->list(array(
    'limit' => 2,
    'amount_lt' => 100,
    'type' => "Debits"  
));

// Accessing transfers in the list and print out value
foreach($transferList as $transfer){
        var_dump($transfer);
    }

// Get the size of the current list 
$transferListSize = count($transferList);

// Get the page object that contains properties including offset/nextCursor, limit.
// Note: refer to the specific api to see if the page object associated is of type pageCursor or pageOffset
$page = transfersList->getPage();

// Get the links 
$links = transfersList->getLinks();

// Check if there is more to list, value equals to False if end of list has been reached 
$hasMore = transfersList->hasMore();

// Get the next 5 elements
$nextTransfersList = transfersList->listNext(5);

Uploading a File

Here's an example of uploading a dispute evidence file.

Copy
Copied
$file =  fopen('test.png', 'r');
$uploadedEvidence = $client->disputes->createDisputeEvidence($disputeId
, new Model\CreateDisputeEvidenceRequest(array('file'=>$file)));

Error Handling

Errors can be caught and handled with try-catch blocks. Here's an example of catching an error and accessing its information.

Copy
Copied
$username = "USimz3zSq5R2PqiEBXY6rSiJ";
$wrongPassword = "123123";

try{
    $invalidClient = new FinixClient($username, $wrongPassword, Environment::SANDBOX);
    $transferList = $invalidClient->transfers->list(array());
}catch(ApiException $e){
    // Print basic http information of the error
    var_dump($e->getCode());
    var_dump($e->getResponseHeader());

    // Print message of each error 
    foreach ($e->getResponseBody() as $error){
        console.log($error["message"]);
        console.log($error["code"]);
    }
}

Supported APIs