Installation & Configuration
The official Perl SDK for the Felloh payments API. Use it to manage bookings, transactions, payment links, and all other Felloh resources from your Perl backend.
Installation
The SDK requires Perl 5.20 or later. It uses HTTP::Tiny for HTTP requests.
Install the SDK
cpanm git://github.com/felloh-org/pearl-sdk.git
Quick Start
Import the Felloh::Client module and create an instance with your API keys. The client handles authentication, token
management, retries, and pagination automatically.
Your API keys can be created and managed from the Felloh dashboard. See the API Keys resource for managing keys programmatically.
Quick Start
use Felloh::Client;
my $client = Felloh::Client->new(
public_key => $ENV{FELLOH_PUBLIC_KEY},
private_key => $ENV{FELLOH_PRIVATE_KEY},
);
# List bookings
my $bookings = $client->bookings->list(
organisation => 'your-org-id',
);
for my $booking (@{ $bookings->{data} }) {
print "$booking->{id} - $booking->{customer_name}\n";
}
Configuration Options
The Felloh::Client->new() constructor accepts the following named parameters.
Parameters
- Name
public_keyrequired- Type
- string
- Description
Your Felloh public API key.
- Name
private_keyrequired- Type
- string
- Description
Your Felloh private API key.
- Name
base_url- Type
- string
- Description
Base URL for the Felloh API. Defaults to
https://api.felloh.com.
- Name
timeout- Type
- integer
- Description
Request timeout in milliseconds. Defaults to
30000(30 seconds).
- Name
max_retries- Type
- integer
- Description
Number of automatic retries on 5xx or network errors. Defaults to
2. Uses exponential backoff.
- Name
token_refresh_buffer- Type
- integer
- Description
Seconds before token expiry to proactively refresh. Defaults to
60.
- Name
logger- Type
- coderef
- Description
Optional callback invoked after every HTTP request for logging and observability. Receives a hash ref with request details.
Full Configuration
use Felloh::Client;
my $client = Felloh::Client->new(
public_key => 'your-public-key',
private_key => 'your-private-key',
base_url => 'https://api.felloh.com',
timeout => 30000,
max_retries => 2,
token_refresh_buffer => 60,
logger => sub {
my ($entry) = @_;
printf "%s %s → %s (%dms)\n",
$entry->{method},
$entry->{url},
$entry->{status_code},
$entry->{duration_ms};
},
);
Token Management
The SDK automatically handles JWT token acquisition and refresh. Tokens are cached in memory and proactively refreshed
before expiry based on the token_refresh_buffer setting. No manual token management is needed.
If a request receives a 401 response, the SDK will automatically refresh the token and retry the request once.
Available Resources
Every resource on the Felloh API is accessible through an accessor method on the client instance.
| Resource | Client Accessor | Documentation |
|---|---|---|
| Organisations | $client->organisations | Organisations |
| Bookings | $client->bookings | Bookings |
| Booking Components | $client->booking_components | Booking Components |
| Transactions | $client->transactions | Transactions |
| Customers | $client->customers | Customers |
| Payment Links | $client->payment_links | Payment Links |
| Ecommerce | $client->ecommerce | Ecommerce |
| Refunds | $client->refunds | Refunds |
| Charges | $client->charges | Charges |
| Chargebacks | $client->chargebacks | Chargebacks |
| Credit Notes | $client->credit_notes | Credit Notes |
| Suppliers | $client->suppliers | Suppliers |
| Beneficiaries | $client->beneficiaries | Beneficiaries |
| Disbursements | $client->disbursements | Disbursements |
| Ledger | $client->ledger | Ledger |
| Acquirer Settlement | $client->batches | Acquirer Settlement |
| API Keys | $client->api_keys | API Keys |
| Audit | $client->audit | Audit |
| AISP | $client->aisp | AISP |
| Scheduled Payments | $client->scheduled_payments | Scheduled Payments |
| Enums | $client->enums | Enums |