fazercards 0.1.0

Official Python SDK for the FazerCards reseller API — gift cards, game top-ups, subscriptions through one REST API.

fazercards

Official Python SDK for the FazerCards 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

pip install fazercards

Requires Python 3.9 or newer. The only runtime dependency is httpx.

Quick start (sync)

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)

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 — the 5-day Gold trial is free and requires no card.

Webhooks (FastAPI)

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:

# 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 for the underlying pattern.

Pagination

# 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

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

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 © FazerCards.