> ## 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.

# Python SDK

> Official Fyatu Python SDK — card issuing, payment collections, and payouts with async support.

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

The official Python SDK for FYATU API v3, with async support and full type hints.

## Requirements

* Python 3.9 or higher

## Installation

```bash theme={null}
pip install fyatu
# or
poetry add fyatu
```

## Quick Start

```python theme={null}
from fyatu import Fyatu

fyatu = Fyatu(
    app_id="your_app_id",
    secret_key="your_secret_key"
)

# Create a collection
collection = fyatu.collections.create(
    amount=10.00,
    currency="USD",
    reference="order_123",
    description="Payment for Order #123",
    customer={
        "email": "customer@example.com",
        "name": "Alice Example"
    },
    redirect_url="https://yoursite.com/payment/success",
    webhook_url="https://yoursite.com/webhooks/fyatu"
)

print(collection.checkout_url)
```

## Async Support

```python theme={null}
import asyncio
from fyatu import AsyncFyatu

async def main():
    fyatu = AsyncFyatu(
        app_id="your_app_id",
        secret_key="your_secret_key"
    )

    # Create multiple collections concurrently
    collections = await asyncio.gather(
        fyatu.collections.create(amount=10, currency="USD", reference="order_1"),
        fyatu.collections.create(amount=20, currency="USD", reference="order_2"),
        fyatu.collections.create(amount=30, currency="USD", reference="order_3"),
    )

    for collection in collections:
        print(f"Created: {collection.id}")

    await fyatu.close()

asyncio.run(main())
```

## Features

* **Full Type Hints** - Complete type annotations for IDE support
* **Async/Await Support** - Both sync and async clients available
* **Pydantic Models** - Response objects with validation
* **Automatic Token Management** - Handles JWT refresh automatically
* **Context Manager** - Proper resource cleanup

## Configuration Options

```python theme={null}
fyatu = Fyatu(
    app_id="your_app_id",
    secret_key="your_secret_key",

    # Optional configuration
    base_url="https://api.fyatu.com/api/v3",
    timeout=30.0,
    max_retries=3,
)
```

## Available Modules

| Module              | 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

```python theme={null}
from fyatu import Fyatu
from fyatu.exceptions import (
    FyatuError,
    ValidationError,
    AuthenticationError,
    InsufficientBalanceError
)

fyatu = Fyatu(app_id="your_app_id", secret_key="your_secret_key")

try:
    payout = fyatu.payouts.create(
        amount=100,
        currency="USD",
        recipient_id="invalid_id"
    )
except ValidationError as e:
    print(f"Validation failed: {e.details}")
except AuthenticationError as e:
    print(f"Authentication failed: {e.message}")
except InsufficientBalanceError as e:
    print(f"Insufficient balance: {e.message}")
except FyatuError as e:
    print(f"API error [{e.code}]: {e.message}")
```

## Webhook Verification

```python theme={null}
from fyatu.webhooks import verify_signature

# Flask example
from flask import Flask, request

app = Flask(__name__)

@app.route("/webhooks/fyatu", methods=["POST"])
def handle_webhook():
    signature = request.headers.get("X-Fyatu-Signature", "")

    is_valid = verify_signature(
        payload=request.data,
        signature=signature,
        secret="your_webhook_secret"
    )

    if not is_valid:
        return "Invalid signature", 401

    event = request.json
    print(f"Received event: {event['type']}")

    return "OK", 200
```

## Django Integration

```python theme={null}
# settings.py
FYATU_APP_ID = "your_app_id"
FYATU_SECRET_KEY = "your_secret_key"

# views.py
from django.conf import settings
from fyatu import Fyatu

fyatu = Fyatu(
    app_id=settings.FYATU_APP_ID,
    secret_key=settings.FYATU_SECRET_KEY
)
```

## Resources

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