Automate Gift Card Delivery in Python with the FazerCards SDK

Selling digital goods at scale means every step between checkout and code delivery must execute without you in the loop. The FazerCards Python SDK is designed for exactly that: a thin client over the REST API that lets you express fulfillment logic in clean business terms rather than raw HTTP calls. This guide walks you through a production-ready integration — catalog browsing, order placement, and webhook handling — in six steps a developer can follow in an afternoon.

Prerequisites

Before you write a line of code, have the following ready:

• A FazerCards account on any plan, or a free 5-day Gold trial for immediate full API access with no card required
• Your API key from the account dashboard
• Python 3.9 or higher in your environment
• A publicly reachable URL for receiving webhooks (a tunneling tool works during development)

Step 1: Install the Package and Connect

Install the SDK from PyPI — the package is named fazercards. Once installed, instantiate the client with your API key. The SDK sets the X-Api-Key header on every outbound request automatically.

As a first smoke test, call the balance endpoint, which maps to GET /balance and returns your current USD balance. If you see a number, you are connected to the production API and ready to proceed. There is no sandbox: the trial runs on production infrastructure, so keep early test orders small and treat them as real charges against your balance.

Step 2: Understand the Catalog Structure

FazerCards exposes three product families, each with its own URL namespace:

• Gift cards — GET /giftcards returns categories; GET /giftcards/cards?category_id=... returns individual offers with card_id, price_usd, and stock
• Top-ups — GET /topups for categories; GET /topups/offers for offers including offer_id and the player-identity fields required at order time
• Game keys — GET /gamekeys and GET /gamekeys/keys follow the same two-step pattern

The SDK provides a method for each of these six calls. Pass results into your data layer and cache them on a schedule — fetching once per hour prevents unnecessary latency. See the full catalog and API docs for the shape of each response object. If you are new to the FazerCards REST API, the gift card API integration guide covers foundational concepts before you bring in the SDK layer.

Step 3: Check Stock Before Showing a Buy Button

The stock field on each offer represents availability right now, but your local cache drifts within minutes for high-demand products. Two practical approaches:

1. Re-fetch the single offer's stock value when a buyer lands on a product detail page — not the whole catalog, just that one item.
2. Mark products unavailable immediately if stock is zero; never let a buyer reach the payment step for an empty offer.

A buyer who hits a failed order because your cache was stale costs more in support time than a marginally slower product page. Webhooks will not help here — they report order events, not stock — so keep refreshing stock on a schedule and right before checkout.

Step 4: Place Orders with Idempotency Keys

Every order request should carry an Idempotency-Key header. Generate one UUID per purchase, persist it alongside the buyer's order record before calling the API, and reuse it on every retry of that purchase. If a network timeout triggers a retry, the API returns the original order instead of creating a duplicate charge. Keys are honored for seven days. The SDK's order methods default to an automatic key, which only protects retries inside a single call; pass your own persisted key so a retry after a crash or restart is covered too.

Order endpoints follow the same pattern across product types:

• POST /giftcards/order requires category_id, card_id, and quantity
• POST /topups/order requires category_id, offer_id, and any player-identity fields the offer specifies
• POST /gamekeys/order follows the same pattern; POST /steam-topup/order takes a Steam login, a currency and an amount instead — see the API docs

The response returns status completed (gift card codes are already in the order's cards field) or processing (delivery is in flight; the webhook handler takes over — the SDK also has a wait helper that polls an order to its final status). Build explicit handlers for failed and refund too — both happen in production.

Step 5: Verify and Handle Webhooks

Register your endpoint URL in the FazerCards dashboard and point it at a dedicated route. Every incoming request carries an X-Webhook-Signature header: sha256= plus the hex HMAC-SHA256 of the raw request body, signed with your webhook secret. The SDK ships a helper that performs this check. Reject any request that fails verification before reading the body.

For orders, the API sends two event types: order.created and order.status_changed. Each payload carries order_id, type, status, and previous_status — no codes in the body. When status arrives as completed, call GET /orders/:orderId immediately to retrieve codes and deliver them. When status is failed or refund, the order could not be fulfilled and the wholesale amount goes back to your balance; tell the buyer and refund them or place a new order with a new key. Open a support ticket with the order ID only if a failed order does not move to refund, or if a delivered code does not redeem — verified cases get a replacement or a balance credit.

Failed deliveries retry at 1, 5, and 30 minutes using the same event_id. Make your handler idempotent: record each event_id on first processing and skip duplicates. The webhooks deep-dive covers edge cases in retry sequencing if your delivery logic is complex.

Step 6: Wire Everything into a Fulfillment Flow

With catalog, orders, and webhooks in place, the complete request lifecycle looks like this:

1. Buyer selects a product; your server validates stock against the refreshed cache.
2. Buyer confirms payment; your server generates a UUID idempotency key and persists it.
3. Your server calls the order endpoint with the idempotency key in the Idempotency-Key header.
4. If the response is completed, take the codes from the response and deliver immediately.
5. If the response is processing, store the order_id and let the webhook handler deliver codes asynchronously.
6. If the response is failed or refund, flag the order and notify the buyer; the wholesale amount returns to your balance, so refund the buyer or retry with a new idempotency key.

Keep your API key in an environment variable, not source code. Expose the webhook route on a separate path from your order endpoints. Store idempotency keys in a durable store that survives application restarts.

What You Have at the End

After these six steps, your Python backend can:

• Cache and refresh the full catalog across gift cards, top-ups, and game keys
• Place orders safely under network failures with no risk of double-charging
• Deliver codes to buyers within seconds of an order completing
• Verify webhook authenticity and deduplicate retried deliveries

Natural next steps: a management interface using GET /orders/:orderId for order lookup, a low-balance alert wired to GET /balance, and rate-limit backoff at the transport layer. The API cookbook has worked examples for both.

If Node.js is your primary runtime, the fazercards npm package mirrors this SDK's structure and connects to the same endpoints — everything in this guide translates directly to a JavaScript or TypeScript environment.

The best way to validate your integration is with real orders on real data. The free 5-day Gold trial unlocks the full API, the complete catalog, and instant delivery — no credit card, no KYC. Start there, place a few small real orders, and confirm end-to-end delivery before you go live with buyers.