FazerCards Python SDK

If you run a shop that sells game currency or gift cards, FazerCards is the wholesaler behind it. You call their API, they deliver the diamonds or the PlayStation code, and your balance goes down. This SDK is the Python side of that conversation.

The problem with retries

Most API clients retry when something goes wrong. For a shop that is dangerous. If the order request timed out, nobody knows whether FazerCards received it. Send it again and the customer may get two top-ups while you pay for both.

So the client sorts failures by what actually happened:

• The connection was refused, so nothing left the machine. It retries.
• The request went out and the answer never came back. It stops and raises OutcomeUnknownError with the order’s idempotency key, so you can look the order up instead of guessing.
• A read failed. Reads are harmless, so it retries with backoff.
• The API said 429. It waits for Retry-After, because that request was not processed.

Every top-up, gift card and Steam order carries an Idempotency-Key. Pass your own order number and a double click or a crash in the middle cannot buy twice. If a reused key comes back with a different item, that is an error, never a success.

Small things that bite in production

• A gift card order can come back completed with an empty list of codes, and the codes show up a moment later. The client reads the order again before returning. If the codes still are not there, order.awaiting_codes is set so the shop never shows a customer an empty result.
• Prices are Decimal all the way through. An amount like 1.005, or True passed as a quantity, is refused before anything is sent.
• Steam amounts always go out with two decimals.
• Telegram purchases take no idempotency key on the API side, so they are never resent.
• Webhooks are checked against their HMAC SHA256 signature in constant time, and bodies over 256 KB are dropped before hashing.

What it covers

Top-ups with player ID validation, gift cards with stock, Telegram Stars and Premium quotes and purchases, Steam login checks and wallet orders, order history with a wait() helper, balance and webhook settings. AsyncFazerCards has the same methods for async code.

Configuration comes from code, environment variables or a fazercards.toml file. Endpoint paths and error messages can be replaced too.

Built with Python, httpx and Pydantic. Typed with mypy, linted with ruff, and covered by 72 tests. MIT licensed.