Felloh 0.1.0

Felloh C# SDK

Official C# SDK for the Felloh payment API.

Installation

dotnet add package Felloh

Quick Start

using Felloh;

var client = new FellohClient(new FellohConfig
{
    PublicKey = "your-public-key",
    PrivateKey = "your-private-key",
});

var bookings = await client.Bookings.ListAsync(new ListBookingsParams
{
    Organisation = "your-org-id",
});

Configuration

var client = new FellohClient(new FellohConfig
{
    PublicKey = "your-public-key",          // Required
    PrivateKey = "your-private-key",        // Required
    BaseUrl = "https://api.felloh.com",     // Default
    Timeout = 30000,                        // Request timeout in ms (default: 30000)
    MaxRetries = 2,                         // Retries on 5xx/network errors (default: 2)
    TokenRefreshBuffer = 60,                // Seconds before token expiry to refresh (default: 60)
    Logger = entry => Console.WriteLine(    // Optional request logger
        $"{entry.Method} {entry.Url} {entry.StatusCode} {entry.DurationMs}ms"),
});

Resources

Usage

List bookings

var response = await client.Bookings.ListAsync(new ListBookingsParams
{
    Organisation = "org-id",
    Skip = 0,
    Take = 20,
});

foreach (var booking in response.Data)
{
    Console.WriteLine($"{booking.Id} - {booking.BookingReference}");
}

Create a booking

var response = await client.Bookings.CreateAsync(new CreateBookingParams
{
    Organisation = "org-id",
    BookingReference = "REF-001",
    CustomerName = "John Smith",
    Email = "john@example.com",
    Currency = "GBP",
    GrossAmount = 150000, // amounts in lowest denomination (pence)
});

Get a single booking

var response = await client.Bookings.GetAsync("booking-id");
Console.WriteLine(response.Data.CustomerName);

Create a payment link

var response = await client.PaymentLinks.CreateAsync(new CreatePaymentLinkParams
{
    Organisation = "org-id",
    CustomerName = "John Smith",
    Email = "john@example.com",
    Amount = 50000,
    Type = "payment",
    OpenBankingEnabled = true,
    CardEnabled = true,
});

Refund a transaction

var response = await client.Transactions.RefundAsync("transaction-id", new RefundTransactionParams
{
    Amount = 5000,
    Description = "Customer requested refund",
});

Pagination

Manual pagination

var page = await client.Bookings.ListAsync(new ListBookingsParams
{
    Organisation = "org-id",
    Skip = 0,
    Take = 25,
});

Console.WriteLine($"Total: {page.Meta.Count}");
Console.WriteLine($"Page items: {page.Data.Count}");

Auto-pagination

Use ListAllAsync() to automatically iterate through all pages:

await foreach (var booking in client.Bookings.ListAllAsync(new ListBookingsParams
{
    Organisation = "org-id",
}))
{
    Console.WriteLine(booking.BookingReference);
}

Or collect all items into a list:

var allBookings = await Paginator.ToListAsync(
    client.Bookings.ListAllAsync(new ListBookingsParams { Organisation = "org-id" }));

Webhook Verification

Verify webhook signatures using HMAC-SHA256 with timing-safe comparison:

using Felloh;

// Returns bool
var isValid = WebhookVerifier.VerifySignature(
    payload: requestBody,
    signature: request.Headers["X-Signature"],
    secret: "your-webhook-secret"
);

// Throws FellohWebhookSignatureException if invalid
WebhookVerifier.AssertSignature(
    payload: requestBody,
    signature: request.Headers["X-Signature"],
    secret: "your-webhook-secret"
);

Error Handling

The SDK throws typed exceptions for different error scenarios:

using Felloh.Errors;

try
{
    await client.Bookings.GetAsync("nonexistent-id");
}
catch (FellohNotFoundException ex)
{
    Console.WriteLine($"Not found: {ex.Message}");
    Console.WriteLine($"Request ID: {ex.Meta?.RequestId}");
}
catch (FellohValidationException ex)
{
    foreach (var error in ex.Errors)
    {
        Console.WriteLine($"{error.Code}: {error.Message}");
    }
}
catch (FellohAuthenticationException)
{
    // Invalid or expired credentials (401)
}
catch (FellohForbiddenException)
{
    // Insufficient permissions (403)
}
catch (FellohRateLimitException)
{
    // Rate limit exceeded (429)
}
catch (FellohServerException)
{
    // Server error (5xx) - automatically retried
}
catch (FellohNetworkException ex)
{
    // Network failure - automatically retried
    Console.WriteLine($"Network error: {ex.InnerException?.Message}");
}

Exception hierarchy

Token Management

The SDK automatically manages JWT tokens:

• Acquires a token on the first API call
• Caches and reuses the token until near expiry
• Proactively refreshes before the token expires (configurable buffer)
• Force-refreshes on 401 responses (once per request)
• Thread-safe concurrent request deduplication

Development

# Build
dotnet build

# Run tests
dotnet test

# Run tests with coverage
dotnet test --collect:"XPlat Code Coverage"

# Pack for NuGet
dotnet pack src/Felloh/Felloh.csproj --configuration Release

License

MIT