> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# C# / .NET SDK

> Official Fyatu .NET SDK — card issuing and payment API client for C# and F# applications.

<Warning>
  This SDK is coming soon. Subscribe to our [changelog](/v3/changelog/overview) to be notified when it's released.
</Warning>

The official .NET SDK for FYATU API v3, supporting C#, F#, and VB.NET.

## Requirements

* .NET 6.0 or higher
* .NET Standard 2.1 (for legacy support)

## Installation

```bash theme={null}
dotnet add package Fyatu.SDK
```

Or via Package Manager:

```powershell theme={null}
Install-Package Fyatu.SDK
```

## Quick Start

```csharp theme={null}
using Fyatu;
using Fyatu.Models;

var fyatu = new FyatuClient(new FyatuOptions
{
    AppId = "your_app_id",
    SecretKey = "your_secret_key"
});

// Create a collection
var collection = await fyatu.Collections.CreateAsync(new CreateCollectionRequest
{
    Amount = 10.00m,
    Currency = "USD",
    Reference = "order_123",
    Description = "Payment for Order #123",
    Customer = new Customer
    {
        Email = "customer@example.com",
        Name = "Alice Example"
    },
    RedirectUrl = "https://yoursite.com/payment/success",
    WebhookUrl = "https://yoursite.com/webhooks/fyatu"
});

Console.WriteLine(collection.CheckoutUrl);
```

## ASP.NET Core Integration

### Configuration

Add to `appsettings.json`:

```json theme={null}
{
  "Fyatu": {
    "AppId": "your_app_id",
    "SecretKey": "your_secret_key"
  }
}
```

### Service Registration

```csharp theme={null}
// Program.cs
builder.Services.AddFyatu(builder.Configuration.GetSection("Fyatu"));

// Or with options
builder.Services.AddFyatu(options =>
{
    options.AppId = "your_app_id";
    options.SecretKey = "your_secret_key";
});
```

### Controller Usage

```csharp theme={null}
[ApiController]
[Route("api/[controller]")]
public class PaymentsController : ControllerBase
{
    private readonly IFyatuClient _fyatu;

    public PaymentsController(IFyatuClient fyatu)
    {
        _fyatu = fyatu;
    }

    [HttpPost]
    public async Task<IActionResult> CreatePayment([FromBody] PaymentRequest request)
    {
        var collection = await _fyatu.Collections.CreateAsync(new CreateCollectionRequest
        {
            Amount = request.Amount,
            Currency = "USD",
            Reference = request.OrderId
        });

        return Ok(new { checkoutUrl = collection.CheckoutUrl });
    }
}
```

## Features

* **.NET 6+ Support** - Uses latest C# features and patterns
* **Dependency Injection** - First-class DI support for ASP.NET Core
* **Async/Await** - All methods are async by default
* **Strong Typing** - Full type safety with nullable reference types
* **Automatic Token Management** - Handles JWT refresh automatically
* **IHttpClientFactory** - Proper HTTP connection management

## Configuration Options

```csharp theme={null}
var fyatu = new FyatuClient(new FyatuOptions
{
    AppId = "your_app_id",
    SecretKey = "your_secret_key",

    // Optional configuration
    BaseUrl = "https://api.fyatu.com/api/v3",
    Timeout = TimeSpan.FromSeconds(30),
    MaxRetries = 3
});
```

## Available Services

| Service             | Description                    |
| ------------------- | ------------------------------ |
| `fyatu.Collections` | Accept payments via checkout   |
| `fyatu.Refunds`     | Manage refunds                 |
| `fyatu.Payouts`     | Send money to recipients       |
| `fyatu.Cardholders` | Manage cardholders             |
| `fyatu.Cards`       | Issue and manage virtual cards |

\| `fyatu.Account` | Access account information |

## Error Handling

```csharp theme={null}
using Fyatu.Exceptions;

try
{
    var payout = await fyatu.Payouts.CreateAsync(new CreatePayoutRequest
    {
        Amount = 100,
        Currency = "USD",
        RecipientId = "invalid_id"
    });
}
catch (ValidationException ex)
{
    Console.WriteLine($"Validation failed: {string.Join(", ", ex.Details)}");
}
catch (AuthenticationException ex)
{
    Console.WriteLine($"Authentication failed: {ex.Message}");
}
catch (InsufficientBalanceException ex)
{
    Console.WriteLine($"Insufficient balance: {ex.Message}");
}
catch (FyatuException ex)
{
    Console.WriteLine($"API error [{ex.Code}]: {ex.Message}");
}
```

## Webhook Verification

```csharp theme={null}
using Fyatu.Webhooks;

[ApiController]
[Route("webhooks")]
public class WebhooksController : ControllerBase
{
    [HttpPost("fyatu")]
    public async Task<IActionResult> HandleFyatuWebhook()
    {
        var signature = Request.Headers["X-Fyatu-Signature"].FirstOrDefault();
        using var reader = new StreamReader(Request.Body);
        var payload = await reader.ReadToEndAsync();

        var isValid = WebhookValidator.VerifySignature(
            payload,
            signature,
            "your_webhook_secret"
        );

        if (!isValid)
        {
            return Unauthorized("Invalid signature");
        }

        var webhookEvent = WebhookEvent.Parse(payload);
        Console.WriteLine($"Received event: {webhookEvent.Type}");

        return Ok();
    }
}
```

## Minimal API Example

```csharp theme={null}
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddFyatu(builder.Configuration.GetSection("Fyatu"));

var app = builder.Build();

app.MapPost("/payments", async (IFyatuClient fyatu, PaymentRequest request) =>
{
    var collection = await fyatu.Collections.CreateAsync(new CreateCollectionRequest
    {
        Amount = request.Amount,
        Currency = "USD",
        Reference = Guid.NewGuid().ToString()
    });

    return Results.Ok(new { checkoutUrl = collection.CheckoutUrl });
});

app.Run();
```

## Resources

* [API Reference](/v3/api-reference/introduction)
* [Webhooks Guide](/v3/concepts/webhooks)
* [GitHub Repository](https://github.com/fyatu/fyatu-dotnet) *(Coming soon)*