felloh/php-sdk

Official PHP SDK for the Felloh API

dev-main 2026-04-01 09:05 UTC

Requires

• php: >=8.1
• guzzlehttp/guzzle: ^7.5

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• api
• payments
• sdk
• felloh

README

Official PHP SDK for the Felloh payments API.

API Documentation | Packagist | GitHub

Installation

composer require felloh/php-sdk

Requires PHP 8.1 or later.

Quick Start

use Felloh\FellohClient;
use Felloh\FellohConfig;

$client = new FellohClient(new FellohConfig(
    publicKey: 'pk_live_...',
    privateKey: 'sk_live_...',
));

// List bookings
$response = $client->bookings->list(['organisation' => 'org-id']);
$bookings = $response['data'];

Configuration

$client = new FellohClient(new FellohConfig(
    publicKey: 'pk_live_...',
    privateKey: 'sk_live_...',
    baseUrl: 'https://sandbox.felloh.com',  // Default: https://api.felloh.com
    timeout: 30.0,                           // Default: 30.0 seconds
    maxRetries: 2,                           // Default: 2
    tokenRefreshBuffer: 60,                  // Default: 60 seconds
    logger: function (\Felloh\LogEntry $entry) {
        echo "{$entry->method} {$entry->url} -> {$entry->statusCode} ({$entry->durationMs}ms)\n";
    },
));

Usage

Bookings

// List
$response = $client->bookings->list(['organisation' => 'org-id']);

// Get
$response = $client->bookings->get('booking-id');

// Create
$response = $client->bookings->create([
    'organisation' => 'org-id',
    'booking_reference' => 'REF-001',
    'customer_name' => 'Jane Smith',
    'email' => '[e-mail]',
]);

// Update
$response = $client->bookings->update('booking-id', ['booking_reference' => 'REF-002']);

// Delete
$response = $client->bookings->delete('booking-id');

Transactions

$response = $client->transactions->list(['organisation' => 'org-id']);
$response = $client->transactions->get('transaction-id');
$response = $client->transactions->refund('transaction-id', ['amount' => 1000]);
$response = $client->transactions->complete('transaction-id');
$response = $client->transactions->reverse('transaction-id');
$response = $client->transactions->reassign('transaction-id', ['booking_id' => 'new-booking-id']);

Payment Links

$response = $client->paymentLinks->list(['organisation' => 'org-id']);
$response = $client->paymentLinks->get('payment-link-id');
$response = $client->paymentLinks->create(['organisation' => 'org-id', /* ... */]);
$response = $client->paymentLinks->delete('payment-link-id');
$response = $client->paymentLinks->assign('payment-link-id', ['booking_id' => 'booking-id']);

Customers

$response = $client->customers->list(['organisation' => 'org-id']);
$response = $client->customers->create(['name' => 'John Doe', 'email' => '[e-mail]']);

Pagination

// Auto-pagination with foreach
foreach ($client->bookings->listAll(['organisation' => 'org-id']) as $booking) {
    echo $booking['id'] . "\n";
}

// Collect all items into an array
$allBookings = $client->bookings->listAll(['organisation' => 'org-id'])->toArray();

Available Resources

Resource	Property	Methods
Organisations	$client->organisations	list
Bookings	$client->bookings	list, listAll, get, create, update, delete, updateReference
Booking Components	$client->bookingComponents	create, delete
Transactions	$client->transactions	list, listAll, get, refund, complete, reverse, reassign
Customers	$client->customers	list, listAll, create
Payment Links	$client->paymentLinks	list, listAll, get, create, delete, assign
Ecommerce	$client->ecommerce	list, listAll, get, create, delete, assign
Refunds	$client->refunds	list, listAll, authorise, decline
Charges	$client->charges	list, listAll
Chargebacks	$client->chargebacks	list, listAll
Credit Notes	$client->creditNotes	list, listAll, get, create, assign
Suppliers	$client->suppliers	list, listAll, create
Beneficiaries	$client->beneficiaries	list, listAll, create, activate
Disbursements	$client->disbursements	list, listAll, get
Ledger	$client->ledger	list, listAll
Batches	$client->batches	list, listAll, get
API Keys	$client->apiKeys	list, create, delete
Audit	$client->audit	list, listAll
AISP	$client->aisp	accounts, transactions, statistics
Scheduled Payments	$client->scheduledPayments	list, listAll, availableTokens, createPayment, approvalLink, delete
Enums	$client->enums	list

Error Handling

use Felloh\Exceptions\FellohAuthenticationError;
use Felloh\Exceptions\FellohNotFoundError;
use Felloh\Exceptions\FellohValidationError;
use Felloh\Exceptions\FellohRateLimitError;
use Felloh\Exceptions\FellohServerError;
use Felloh\Exceptions\FellohNetworkError;

try {
    $client->bookings->get('nonexistent-id');
} catch (FellohNotFoundError $e) {
    echo "Not found: {$e->getMessage()}\n";
    echo "Status: {$e->statusCode}\n";
    echo "Request ID: {$e->meta['request_id']}\n";
} catch (FellohAuthenticationError $e) {
    echo "Invalid credentials\n";
} catch (FellohValidationError $e) {
    echo "Validation: {$e->getMessage()}\n";
} catch (FellohRateLimitError $e) {
    echo "Rate limited\n";
} catch (FellohServerError $e) {
    echo "Server error (retries exhausted)\n";
} catch (FellohNetworkError $e) {
    echo "Network error: {$e->getMessage()}\n";
}

Webhook Verification

use Felloh\Webhooks;

// Returns boolean
$isValid = Webhooks::verifyWebhookSignature(
    payload: $requestBody,
    signature: $_SERVER['HTTP_X_SIGNATURE'],
    secret: 'your_webhook_secret',
);

// Throws FellohWebhookSignatureError on failure
Webhooks::assertWebhookSignature(
    payload: $requestBody,
    signature: $_SERVER['HTTP_X_SIGNATURE'],
    secret: 'your_webhook_secret',
);

Development

composer install
composer test

Other SDKs

• Node.js SDK - npm install @felloh-org/node-sdk
• Python SDK - pip install felloh

License

MIT