Fyber 1.0.1

Fyber .NET SDK

Official .NET SDK for the Fyber Payment API.

Requirements

• .NET 8.0 or higher

Installation

dotnet add package Fyber

Or via the NuGet Package Manager:

Install-Package Fyber

Quick Start

using Fyber;
using Fyber.Models;

// Initialize the client
var fyber = new FyberClient("sk_test_your_api_key", new FyberClientOptions
{
    Environment = "test" // or "live" for production
});

// Create a checkout session (recommended)
var session = await fyber.Checkout.Sessions.CreateAsync(new CreateCheckoutSessionRequest
{
    Mode = "payment",
    Amount = 5000, // $50.00 in cents
    Currency = "JMD",
    SuccessUrl = "https://yoursite.com/success?session_id={SESSION_ID}",
    CancelUrl = "https://yoursite.com/cancel",
    LineItems = new List<LineItem>
    {
        new LineItem { Name = "Pro Plan", Quantity = 1, UnitAmount = 5000 }
    },
    CustomerEmail = "customer@example.com"
});

// Redirect customer to hosted checkout
Console.WriteLine($"Checkout URL: {session.Url}");

Hosted Checkout (Recommended)

The easiest way to accept payments. Redirect customers to a Fyber-hosted checkout page that handles card input, validation, and 3DS authentication.

// Create a checkout session
var session = await fyber.Checkout.Sessions.CreateAsync(new CreateCheckoutSessionRequest
{
    Mode = "payment",
    Amount = 5000, // $50.00 in cents
    Currency = "JMD",
    SuccessUrl = "https://yoursite.com/success?session_id={SESSION_ID}",
    CancelUrl = "https://yoursite.com/cancel",
    LineItems = new List<LineItem>
    {
        new LineItem { Name = "Pro Plan", Quantity = 1, UnitAmount = 5000 }
    },
    CustomerEmail = "customer@example.com",
    Metadata = new Dictionary<string, object>
    {
        { "orderId", "1234" }
    }
});

// Redirect customer to checkout
return Redirect(session.Url);

After payment, the customer is redirected to your success URL. Use webhooks to confirm payment:

// Retrieve the session to verify payment
var session = await fyber.Checkout.Sessions.GetBySessionIdAsync("cs_test_...");

if (session.Status == "complete")
{
    // Payment successful, fulfill the order
    Console.WriteLine($"Payment ID: {session.PaymentId}");
}

Checkout modes:

• payment - One-time payment (default)
• setup - Save card for future use without charging
• subscription - Start a recurring subscription

Payment intents:

• sale - Charge immediately (default)
• authorize - Authorize only, capture later
• verify - Validate card with $0 auth

// Expire a session manually
await fyber.Checkout.Sessions.ExpireAsync(session.Id);

// List all sessions
var sessions = await fyber.Checkout.Sessions.ListAsync(new ListCheckoutSessionsOptions
{
    Status = "complete",
    Limit = 20
});

Payments

Create a Payment

var payment = await fyber.Payments.CreateAsync(new CreatePaymentRequest
{
    Amount = 5000,
    Currency = "USD",
    Source = new CardSource
    {
        Number = "4111111111111111",
        ExpMonth = 12,
        ExpYear = 2025,
        Cvv = "123"
    },
    Customer = new CustomerInput
    {
        Email = "customer@example.com",
        Name = "John Doe"
    },
    Capture = true, // Capture immediately (default)
    Metadata = new Dictionary<string, object>
    {
        { "orderId", "12345" }
    }
});

Authorize and Capture Separately

// Authorize only
var payment = await fyber.Payments.CreateAsync(new CreatePaymentRequest
{
    Amount = 5000,
    Currency = "USD",
    Source = new CardSource { /* ... */ },
    Capture = false
});

// Capture later
var captured = await fyber.Payments.CaptureAsync(payment.Id);

// Or capture a partial amount
var captured = await fyber.Payments.CaptureAsync(payment.Id, new CapturePaymentRequest
{
    Amount = 3000 // Capture $30 of the $50 authorized
});

Retrieve a Payment

var payment = await fyber.Payments.GetAsync("pay_abc123");

List Payments

var payments = await fyber.Payments.ListAsync(new ListPaymentsOptions
{
    Limit = 10,
    Status = "succeeded"
});

foreach (var payment in payments.Data)
{
    Console.WriteLine($"{payment.Id}: {payment.Amount}");
}

Cancel a Payment

await fyber.Payments.CancelAsync("pay_abc123");

Refunds

Create a Refund

// Full refund
var refund = await fyber.Refunds.CreateAsync(new CreateRefundRequest
{
    PaymentId = "pay_abc123"
});

// Partial refund
var refund = await fyber.Refunds.CreateAsync(new CreateRefundRequest
{
    PaymentId = "pay_abc123",
    Amount = 500, // Refund $5.00
    Reason = "Customer request"
});

Retrieve a Refund

var refund = await fyber.Refunds.GetAsync("ref_abc123");

List Refunds

var refunds = await fyber.Refunds.ListAsync(new ListRefundsOptions
{
    PaymentId = "pay_abc123"
});

Customers

Create a Customer

var customer = await fyber.Customers.CreateAsync(new CreateCustomerRequest
{
    Email = "customer@example.com",
    Name = "John Doe",
    Phone = "+1234567890",
    Address = new Address
    {
        Line1 = "123 Main St",
        City = "Kingston",
        PostalCode = "12345",
        Country = "JM"
    }
});

Update a Customer

var customer = await fyber.Customers.UpdateAsync("cus_abc123", new UpdateCustomerRequest
{
    Name = "Jane Doe",
    Phone = "+0987654321"
});

Delete a Customer

await fyber.Customers.DeleteAsync("cus_abc123");

List Customers

var customers = await fyber.Customers.ListAsync(new ListCustomersOptions
{
    Limit = 20,
    Email = "customer@example.com"
});

Tokens (Saved Cards)

Save cards for future payments using hosted checkout with mode: 'setup':

// Create a setup session to save a card
var session = await fyber.Checkout.Sessions.CreateAsync(new CreateCheckoutSessionRequest
{
    Mode = "setup",
    CustomerId = "cus_123",
    SuccessUrl = "https://yoursite.com/card-saved?session_id={SESSION_ID}",
    CancelUrl = "https://yoursite.com/cancel"
});

// After checkout completes, the token is available via webhook
// or by retrieving the session
var completedSession = await fyber.Checkout.Sessions.GetBySessionIdAsync("cs_test_...");
var tokenId = completedSession.TokenId;

// List customer's saved cards
var tokens = await fyber.Tokens.ListAsync(new ListTokensOptions
{
    CustomerId = "cus_123"
});

// Get a specific token
var token = await fyber.Tokens.GetAsync("tok_123");

// Set as default payment method
await fyber.Tokens.SetDefaultAsync("tok_123");

// Delete a saved card
await fyber.Tokens.DeleteAsync("tok_123");

// Use a saved card for payment
var payment = await fyber.Payments.CreateAsync(new CreatePaymentRequest
{
    Amount = 5000,
    Currency = "JMD",
    TokenId = "tok_123"
});

Subscriptions

Create recurring billing subscriptions:

// First, save a card using hosted checkout (mode: 'setup')
// Then create a subscription with the token

var subscription = await fyber.Subscriptions.CreateAsync(new CreateSubscriptionRequest
{
    CustomerId = "cus_123",
    TokenId = "tok_123", // From saved card
    Amount = 999, // $9.99/month
    Currency = "JMD",
    Interval = "month", // "day", "week", "month", "year"
    TrialDays = 14, // Optional trial period
    Metadata = new Dictionary<string, object>
    {
        { "plan", "pro" }
    }
});

// Get subscription
var sub = await fyber.Subscriptions.GetAsync("sub_123");

// List subscriptions
var subs = await fyber.Subscriptions.ListAsync(new ListSubscriptionsOptions
{
    CustomerId = "cus_123",
    Status = "active"
});

// Pause a subscription
await fyber.Subscriptions.PauseAsync("sub_123");

// Resume a paused subscription
await fyber.Subscriptions.ResumeAsync("sub_123");

// Cancel subscription
await fyber.Subscriptions.CancelAsync("sub_123", new CancelSubscriptionOptions
{
    CancelAtPeriodEnd = true, // Cancel at end of billing period
    Reason = "Customer requested"
});

// Get subscription stats
var stats = await fyber.Subscriptions.StatsAsync();
Console.WriteLine($"Active: {stats.ActiveCount}, MRR: ${stats.Mrr / 100}");

Subscription webhook events:

• subscription.created - Subscription activated
• subscription.payment_succeeded - Recurring payment successful
• subscription.payment_failed - Recurring payment failed
• subscription.trial_ending - Trial ends in 3 days
• subscription.canceled - Subscription canceled

Installments (BNPL)

Split payments into installment plans:

// Check customer eligibility
var eligibility = await fyber.Installments.CheckEligibilityAsync(new CheckEligibilityRequest
{
    CustomerId = "cus_123",
    Amount = 50000 // $500.00
});

if (eligibility.Eligible)
{
    Console.WriteLine($"Available options: {string.Join(", ", eligibility.AvailableOptions)} installments");
    Console.WriteLine($"Available credit: ${eligibility.AvailableCredit / 100}");
}

// Create an installment plan (requires saved card)
var plan = await fyber.Installments.CreateAsync(new CreateInstallmentRequest
{
    CustomerId = "cus_123",
    TokenId = "tok_123",
    TotalAmount = 50000, // $500.00 total
    InstallmentCount = 4, // 4 payments
    Frequency = "biweekly", // "weekly", "biweekly", "monthly"
    Metadata = new Dictionary<string, object>
    {
        { "orderId", "1234" }
    }
});

// Get installment plan
var plan = await fyber.Installments.GetAsync("inst_123");

// List installment plans
var plans = await fyber.Installments.ListAsync(new ListInstallmentsOptions
{
    CustomerId = "cus_123",
    Status = "active"
});

// Cancel an installment plan
await fyber.Installments.CancelAsync("inst_123");

// Get installment stats
var stats = await fyber.Installments.StatsAsync();
Console.WriteLine($"Active plans: {stats.ActiveCount}");
Console.WriteLine($"Default rate: {stats.DefaultRate * 100}%");

Installment webhook events:

• installment.plan_created - Plan activated, first payment charged
• installment.payment_succeeded - Scheduled payment completed
• installment.payment_failed - Payment failed (may retry)
• installment.plan_completed - All payments completed
• installment.plan_defaulted - Customer defaulted

Webhooks

Verify Webhook Signature

using Fyber;
using Fyber.Models;

// In your webhook handler (e.g., ASP.NET Core controller)
[HttpPost("webhook")]
public IActionResult HandleWebhook()
{
    var payload = new StreamReader(Request.Body).ReadToEnd();
    var signature = Request.Headers["fyber-signature"].ToString();
    var secret = "whsec_your_webhook_secret";

    try
    {
        var webhookEvent = FyberClient.VerifyWebhook(payload, signature, secret);

        // Handle the event
        switch (webhookEvent.Type)
        {
            case "checkout.session.completed":
                // Checkout payment successful - fulfill order
                break;
            case "payment.succeeded":
                // Handle successful payment
                break;
            case "payment.failed":
                // Handle failed payment
                break;
            case "refund.created":
                // Handle refund
                break;
        }

        return Ok();
    }
    catch (Fyber.Exceptions.FyberException ex)
    {
        // Invalid signature
        return BadRequest("Invalid signature");
    }
}

Error Handling

using Fyber.Exceptions;

try
{
    var payment = await fyber.Payments.CreateAsync(request);
}
catch (FyberException ex)
{
    Console.WriteLine($"Error: {ex.Message}");
    Console.WriteLine($"Type: {ex.Type}");
    Console.WriteLine($"Code: {ex.ErrorCode}");
    Console.WriteLine($"Status: {ex.StatusCode}");
}

Configuration

var fyber = new FyberClient("sk_test_xxx", new FyberClientOptions
{
    Environment = "live",        // "test" or "live"
    BaseUrl = "https://...",     // Custom API URL (optional)
    Timeout = 60                 // Request timeout in seconds
});

License

MIT