Fena PHP Payment SDK

PHP SDK for working with Fena payment APIs.

Requirements

PHP 7.4.0 and later.

Introduction

Welcome to the Fena PHP Payment SDK guide. Before we dive into integration, let us explain how this system works.

How Fena online payments works

The Fena Online Payment system consists of three main parts

1. A webpage that initiates a request to Fena to make a payment.
2. A page on your webserver that Fena to notify you when a payment has been made.
3. A webpage that confirms the above payment and passes the customer on to the next phase of your application, such as your ‘order confirmation’ or 'Thank You' page.

Installation

You can install the bindings via Composer. Run the following command:

composer require fena/toolkit-php-payment-sdk

To use the bindings, use Composer's autoload:

require_once('vendor/autoload.php');

Dependencies

• json
• mbstring (Multibyte String)

Getting Started

Simple new payment looks like:

use Fena\PaymentSDK\Connection;
use Fena\PaymentSDK\Payment;

$connection = Connection::createConnection(
    $integrationId = '8afa74ae-6ef9-48bb-93b2-9fe8be53db50',
    $integrationSecret = '55d7d5ed-be22-4321-bb3f-aec8524d8be2'
);

$payment = Payment::createPayment(
    $connection,
    $amount = '10.00'
    $reference = 'AA-11',
    $bankId = '8afa74ae9fe8be53db50'
);
 
$payment->process();

Optional: Set User or Pre Selected Provider For New Payment

use Fena\PaymentSDK\Connection;
use Fena\PaymentSDK\Payment;
use Fena\PaymentSDK\Provider;
use Fena\PaymentSDK\User;

$connection = Connection::createConnection($integrationId, $integrationSecret);
$payment = Payment::createPayment(
    $connection,
    $amount = '10.00',
    $reference = 'AA-11', 
    $bankId = '8afa74ae9fe8be53db50'
);

$user = User::createUser(
    $email = 'john.doe@test.com',
    $firstName = 'John',
    $lastName = 'Doe',
    $contactNumber = '07000845953'
);
$payment->setUser($user);

$provider = Provider::createProvider(
    $providerId = 'lloyds-bank',
    $sortCode = '123456',
    $accountNumber = '12345678'
);
$payment->setProvider($provider);

Connection

Our SDK uses connection objects for most requests. To create a new connection object call a static method of Fena\PaymentSDK\Connection::createConnection.

use Fena\PaymentSDK\Connection;

$connection = Connection::createConnection(
    $integrationId = '62b47dec6ba2cd6a040b1953',
    $integrationSecret = '55d7d5ed-be22-4321-bb3f-aec8524d8be2'
);

Make sure to use your own $integrationId and $integrationSecret values.

Input Arguments

Argument	Required	Description
Integration Id	Yes	Integration ID of terminal, this is an Object ID
Terminal Secret	Yes	Terminal Secret of terminal. Must be UUID 4.

If valid, arguments are given object of Fena\PaymentSDK\Connection will be returned. Otherwise, Object of Fena\PaymentSDK\Error will be returned.

Return Object

Operation	Class Object
Success	Fena\PaymentSDK\Connection
Error	Fena\PaymentSDK\Error Code 1
Error	Fena\PaymentSDK\Error Code 2

Payment

To create a new payment call a static method of Fena\PaymentSDK\Payment::createPayment.

use Fena\PaymentSDK\Payment;
$payment = Payment::createPayment(
    $connection,
    $amount = '10.00',
    $reference = 'AA-11',
    $bankId = '8afa74ae9fe8be53db50'
);

Make sure your reference is unique

Input Arguments

Argument	Required	Description
Connection	Yes	Connection object.
Reference	Yes	Your payment reference. Must not be empty and cannot be more than 255 characters.
Amount	Yes	Amount requested must be in 2 decimal places, string and greater than 0.00.
Bank Id	No	the bank id you want to receive payment in

If valid, arguments are given object of Fena\PaymentSDK\Payment will be returned. Otherwise, Object of Fena\PaymentSDK\Error will be returned.

Return Object

Operation	Class Object
Success	Fena\PaymentSDK\Payment
Error	Fena\PaymentSDK\Error Code 3
Error	Fena\PaymentSDK\Error Code 4
Error	Fena\PaymentSDK\Error Code 5
Error	Fena\PaymentSDK\Error Code 6

Payment Process

To process payment call Process on the Payment object. You can also pass false to process function this will return the url as string.

$payment->process();

Provider

If you want to predefine the account provider or force the customer to pay from a certain account you can use the Provider object. To Create a new Provider call a static method of Fena\PaymentSDK\Provider::createProvider and then call setProvider on payment object with provider object as argument.

use Fena\PaymentSDK\Provider;
$provider = Provider::createProvider(
    $providerId = 'ob-lloyds-personal',
    $sortCode = '123456',
    $accountNumber = '12345678'
);

$payment->setProvider($provider);

**Full list of supported provider ids can be found using this endpoint

https://app.fena.co/api/providers**

Input Arguments

Argument	Required	Description
Provider ID	Yes	Must be a value of provider given by Fena.
Sort Code	*No	Must be 6 digits and numeric. Cannot empty if Account Number is given.
Account Number	*No	Must be 8 digits and numeric. Cannot empty if Sort Code is given.

If valid, arguments are given object of Fena\PaymentSDK\Provider will be returned. Otherwise, Object of Fena\PaymentSDK\Error will be returned.

Return Object

Operation	Class Object
Success	Fena\PaymentSDK\Provider
Error	Fena\PaymentSDK\Error Code 7
Error	Fena\PaymentSDK\Error Code 8
Error	Fena\PaymentSDK\Error Code 9
Error	Fena\PaymentSDK\Error Code 10

User

If you want to send the customers details to Fena. You can set customer detail using User object. To Create a new User call a static method of Fena\PaymentSDK\User::createUser and then call setUser on payment object with user object as argument.

use Fena\PaymentSDK\User;
$user = User::createUser(
    $email = 'john.doe@test.com',
    $firstName = 'John',
    $lastName = 'Doe',
    $contactNumber = '07000845953'
);

$payment->setUser($user);

Input Arguments | Argument | Required | Description | |------------|----------|------------------------------------------------------------------------| | Email | No | Must be valid email. Can be null. Must not be more than 255 characters.| | First Name | No | Can be null. Must not be more than 255 characters. | | Last Name | No | Can be null. Must not be more than 255 characters. |

If valid, arguments are given object of Fena\PaymentSDK\User will be returned. Otherwise, Object of Fena\PaymentSDK\Error will be returned.

Return Object

Operation	Class Object
Success	Fena\PaymentSDK\User
Error	Fena\PaymentSDK\Error Code 12
Error	Fena\PaymentSDK\Error Code 13
Error	Fena\PaymentSDK\Error Code 14
Error	Fena\PaymentSDK\Error Code 15

Errors

Any errors in SDK are handled via the Fena\PaymentSDK\Error object.

$error->getCode();
$error->getMessage();

The PHP SDK uses the following error codes:

Error Code	Meaning
1	Invalid Terminal ID
2	Invalid Terminal Secret
3	Order ID cannot be empty
4	Amount cannot be empty or less than 0.01
5	Number must be 2 decimal places
6	Order ID cannot be greater than 255 characters
7	Invalid Sort Code
8	Invalid Account Number
9	Provider ID must be set to set sort code and account number
10	Sort Code and account both must be set
11	Invalid email is given
12	First name need to be less than 255
13	Last name need to be less than 255
14	Contact Number need to be less than 255
15	Email need to be less than 255