Installation & Configuration
The official Ruby SDK for the Felloh payments API. Use it to manage bookings, transactions, payment links, and all other Felloh resources from your server.
Installation
The SDK requires Ruby 3.1 or later. It is distributed via GitHub Packages.
Add the GitHub Packages source and the gem to your Gemfile:
Install the SDK
source "https://rubygems.pkg.github.com/felloh-org" do
gem "felloh"
end
Authenticate with GitHub Packages using bundle config:
Authenticate
bundle config https://rubygems.pkg.github.com/felloh-org USERNAME:TOKEN
Where TOKEN is a GitHub personal access token with read:packages scope.
Quick Start
Create a Felloh::Client 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
require "felloh"
client = Felloh::Client.new(
public_key: ENV["FELLOH_PUBLIC_KEY"],
private_key: ENV["FELLOH_PRIVATE_KEY"],
)
# List bookings
bookings = client.bookings.list(
organisation: "your-org-id",
)
puts bookings.data
Configuration Options
The Felloh::Client constructor accepts the following options.
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 seconds. Defaults to
30.
- 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
- Proc
- Description
Optional callback invoked after every HTTP request for logging and observability. Receives a hash with request details.
Full Configuration
client = Felloh::Client.new(
public_key: "your-public-key",
private_key: "your-private-key",
base_url: "https://api.felloh.com",
timeout: 30,
max_retries: 2,
token_refresh_buffer: 60,
logger: ->(entry) {
puts "#{entry[:method]} #{entry[:url]}" \
" #{entry[:status_code]}" \
" #{entry[:duration_ms]}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 a method on the client instance.
| Resource | Client Property | 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 |