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
- A webpage that initiates a request to Fena to make a payment.
- A page on your webserver that Fena to notify you when a payment has been made.
- 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​
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 |