Metadata-Version: 2.4
Name: fazercards
Version: 0.1.0
Summary: Official Python SDK for the FazerCards reseller API — gift cards, game top-ups, subscriptions through one REST API.
Author-email: FazerCards <support@fazercards.com>
License: MIT
Project-URL: Homepage, https://reseller.fazercards.com
Project-URL: Documentation, https://reseller.fazercards.com/en/docs
Project-URL: Cookbook, https://reseller.fazercards.com/en/docs/cookbook
Project-URL: Source, https://github.com/FZR-cards/fazercards-python
Project-URL: Issues, https://github.com/FZR-cards/fazercards-python/issues
Project-URL: Changelog, https://github.com/FZR-cards/fazercards-python/releases
Keywords: fazercards,reseller,gift-cards,gift-card-api,game-topup,pubg-uc,free-fire,roblox,steam-wallet,wholesale,b2b,telegram-bot,aiogram,discord-bot,usdt,crypto-payments,binance-pay,webhooks,rest-api
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1.0,>=0.25
Requires-Dist: typing_extensions>=4.7; python_version < "3.11"
Dynamic: license-file

# fazercards

[![PyPI](https://img.shields.io/pypi/v/fazercards.svg)](https://pypi.org/project/fazercards/)
[![Python](https://img.shields.io/pypi/pyversions/fazercards.svg)](https://pypi.org/project/fazercards/)
[![License](https://img.shields.io/pypi/l/fazercards.svg)](./LICENSE)

Official Python SDK for the [FazerCards](https://reseller.fazercards.com) reseller API — sell **gift cards, mobile game top-ups, subscriptions and game keys** through a single REST contract with instant automated delivery.

Both **sync** and **async** clients are included, so the same package works in:

- **aiogram / discord.py / FastAPI** (async)
- **Django / Flask / scripts / cron jobs** (sync)

Catalog: 10 000+ SKUs across Amazon, Steam, PSN, Xbox, Google Play, iTunes, Nintendo, Roblox, PUBG Mobile UC, Free Fire, Mobile Legends, Genshin, Valorant, ...

Full reference: <https://reseller.fazercards.com/en/docs> · Cookbook recipes: <https://reseller.fazercards.com/en/docs/cookbook>

---

## Install

```bash
pip install fazercards
```

Requires Python 3.9 or newer. The only runtime dependency is [`httpx`](https://www.python-httpx.org).

## Quick start (sync)

```python
import os
from fazercards import FazerCardsClient

with FazerCardsClient(api_key=os.environ["FAZER_API_KEY"]) as fz:
    # 1. Browse the catalog
    page = fz.catalog.list(category="gift-cards", limit=50)
    for sku in page["items"]:
        print(sku["id"], sku.get("name"), sku.get("priceUsd"), "USD")

    # 2. Place an order
    order = fz.orders.create(
        sku_id="amazon-us-10",
        quantity=1,
        idempotency_key="auto",  # generates a UUID, reused on retries
    )

    # 3. Read code / poll status
    result = fz.orders.get(order["id"])
    print(result["status"], result.get("code"))
```

## Quick start (async — aiogram / FastAPI / discord.py)

```python
import os, asyncio
from fazercards import FazerCardsAsyncClient

async def main():
    async with FazerCardsAsyncClient(api_key=os.environ["FAZER_API_KEY"]) as fz:
        balance = await fz.balance.get()
        print("Balance:", balance["balance_usd"], "USD")

        order = await fz.orders.create(
            sku_id="pubg-uc-60",
            quantity=1,
            metadata={"player_id": "5123456789"},
            idempotency_key="auto",
        )
        print(order["id"], order["status"])

asyncio.run(main())
```

The SDK handles:
- `X-Api-Key` authentication
- JSON encoding / decoding
- Per-request timeouts (default 30s)
- Automatic retries on HTTP 429 + 5xx with `Retry-After`-aware exponential backoff and ±15 % jitter
- A typed error hierarchy you can `except` on

Get an API key from the [reseller panel](https://reseller.fazercards.com/en/free-trial) — the 5-day Gold trial is free and requires no card.

## Webhooks (FastAPI)

```python
import os
from fastapi import FastAPI, HTTPException, Request
from fazercards import parse_webhook_event

app = FastAPI()
SECRET = os.environ["FAZER_WEBHOOK_SECRET"]

@app.post("/webhooks/fazercards")
async def webhook(request: Request):
    raw = await request.body()
    sig = request.headers.get("x-fazercards-signature", "")
    try:
        event = parse_webhook_event(raw, sig, SECRET)
    except ValueError as err:
        raise HTTPException(401, str(err))

    if event["type"] == "order.completed":
        deliver_to_customer(event["order"])
    elif event["type"] == "order.failed":
        notify_failure(event["order"], event.get("reason"))
    elif event["type"] == "order.refunded":
        refund_customer(event["order"])

    return {"ok": True}
```

Signatures are HMAC-SHA256 of the raw body, hex-encoded in `X-FazerCards-Signature`. Comparison is timing-safe (`hmac.compare_digest`).

## Idempotency

`orders.create()` and `payments.create()` honour the `Idempotency-Key` header. Three accepted forms:

```python
# 1. Explicit value — generate once, reuse across retries of the SAME logical order.
fz.orders.create(sku_id="amazon-us-10", idempotency_key="order-2026-05-25-abc123")

# 2. "auto" — SDK generates a UUID4 per call.
fz.orders.create(sku_id="amazon-us-10", idempotency_key="auto")

# 3. Omitted — no key sent. Avoid in production.
fz.orders.create(sku_id="amazon-us-10")
```

## Rate limits

The public API uses per-category sliding windows so polling order status can't starve order creation:

| Category | Limit |
|---|---|
| Catalog read (`GET /catalog`, `/prices`, `/skus`) | 30 / min |
| Order create (`POST /order`, `/topup`, ...) | 60 / min |
| Order status (`GET /order/{id}` polling) | 120 / min |
| Account read (`GET /me`, `/balance`, `/subscription`) | 30 / min |
| Payment write (`POST /payments`) | 15 / min |
| Default (everything else) | 120 / min |
| Login | 10 attempts / 15 min per IP |

Counter key is `(category × API key)` — categories don't share budget. On overshoot the SDK auto-retries with `Retry-After`-aware backoff and jitter. See the [rate-limit cookbook recipe](https://reseller.fazercards.com/en/docs/cookbook#rate-limit-handling) for the underlying pattern.

## Pagination

```python
# Sync iterator over every SKU in a category (walks pages automatically).
for sku in fz.catalog.list_all(category="gift-cards"):
    process(sku)

# Async version:
async for sku in fz.catalog.list_all(category="gift-cards"):
    await process(sku)
```

## Errors

```python
from fazercards import (
    FazerCardsClient,
    FazerCardsError,
    FazerCardsAuthError,
    FazerCardsNotFoundError,
    FazerCardsRateLimitError,
    FazerCardsServerError,
)

try:
    fz.orders.create(sku_id="amazon-us-10")
except FazerCardsAuthError:
    # Rotate / replace the API key.
    ...
except FazerCardsRateLimitError as err:
    print("Throttle for", err.retry_after_seconds, "s")
except FazerCardsServerError:
    # The SDK already auto-retried up to `retries`; surface to ops.
    ...
except FazerCardsError as err:
    print("API error", err.status, err.code, err.message)
```

## Client options

```python
FazerCardsClient(
    api_key="live_xxx",                             # required (or set FAZER_API_KEY env)
    base_url="https://api.fazercards.com/api/v2",   # default
    timeout=30.0,                                   # seconds
    retries=3,                                      # set 0 to disable
    app_name="my-bot/1.4",                          # prefix the User-Agent
    http_client=None,                               # pass your own httpx.Client / httpx.AsyncClient
)
```

## More

- API documentation: <https://reseller.fazercards.com/en/docs>
- Cookbook (curl / Node / Python / Go recipes): <https://reseller.fazercards.com/en/docs/cookbook>
- Webhooks guide: <https://reseller.fazercards.com/en/docs/webhooks>
- Glossary: <https://reseller.fazercards.com/en/glossary>
- Node.js SDK: <https://github.com/FZR-cards/fazercards-node>
- Free trial: <https://reseller.fazercards.com/en/free-trial>
- Telegram channel: <https://t.me/FazerCardsReseller>

## License

[MIT](./LICENSE) © FazerCards.
