Skip to main content

Fena PHP Payment SDK

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/php-payment-sdk

To use the bindings, use Composer's autoload:

require_once('vendor/autoload.php');

Dependencies

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',
);

$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',
);

$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

ArgumentRequiredDescription
Integration IdYesIntegration ID of terminal, this is an Object ID
Terminal SecretYesTerminal 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

OperationClass Object
SuccessFena\PaymentSDK\Connection
ErrorFena\PaymentSDK\Error Code 1
ErrorFena\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'
);

Make sure your reference is unique

Input Arguments

ArgumentRequiredDescription
ConnectionYesConnection object.
ReferenceYesYour payment reference. Must not be empty and cannot be more than 255 characters.
AmountYesAmount requested must be in 2 decimal places, string and greater than 0.00.

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

Return Object

OperationClass Object
SuccessFena\PaymentSDK\Payment
ErrorFena\PaymentSDK\Error Code 3
ErrorFena\PaymentSDK\Error Code 4
ErrorFena\PaymentSDK\Error Code 5
ErrorFena\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

ArgumentRequiredDescription
Provider IDYesMust be a value of provider given by Fena.
Sort Code*NoMust be 6 digits and numeric. Cannot empty if Account Number is given.
Account Number*NoMust 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

OperationClass Object
SuccessFena\PaymentSDK\Provider
ErrorFena\PaymentSDK\Error Code 7
ErrorFena\PaymentSDK\Error Code 8
ErrorFena\PaymentSDK\Error Code 9
ErrorFena\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

OperationClass Object
SuccessFena\PaymentSDK\User
ErrorFena\PaymentSDK\Error Code 12
ErrorFena\PaymentSDK\Error Code 13
ErrorFena\PaymentSDK\Error Code 14
ErrorFena\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 CodeMeaning
1Invalid Terminal ID
2Invalid Terminal Secret
3Order ID cannot be empty
4Amount cannot be empty or less than 0.01
5Number must be 2 decimal places
6Order ID cannot be greater than 255 characters
7Invalid Sort Code
8Invalid Account Number
9Provider ID must be set to set sort code and account number
10Sort Code and account both must be set
11Invalid email is given
12First name need to be less than 255
13Last name need to be less than 255
14Contact Number need to be less than 255
15Email need to be less than 255