Back to blog

Fault-Tolerant Gift Card API Orders: A Developer's Guide

FazerCards
Fault-Tolerant Gift Card API Orders: A Developer's Guide

Every reseller who automates gift card fulfilment eventually faces the same three failure scenarios: a timeout that leaves an order in an unknown state, a network hiccup that triggers a retry and bills the account twice, or a webhook that arrives while the server is restarting. At low volume these events are annoying. At scale each one costs real money. The difference between a fragile prototype and a production system is how deliberately you design against them.

Prerequisites

You need an active FazerCards account with API credentials, a server-side backend with an HTTP client and a crypto library, and a publicly reachable HTTPS endpoint for receiving webhooks. The API docs cover endpoint signatures and status codes. The cookbook has ready-to-use patterns for common flows. If you are new to the platform, who FazerCards is for and the pricing plans give a fast overview.

What you will have at the end: a fault-tolerant order flow with idempotency, exponential backoff, and HMAC webhook verification — the three patterns that take an integration from demo quality to production quality.

Step 1: Map the Order State Machine

A FazerCards order moves through a small set of statuses: processing (fulfilment in progress), then a final completed (codes ready) or failed (the order could not be fulfilled). Many instant products are already completed in the initial response; others finish asynchronously. The dangerous assumption many integrations make is that a non-200 response means nothing happened. A TCP timeout at exactly the moment the server accepted the request leaves you with a live order and no confirmation on your side. A naive retry creates a duplicate charge and a duplicate code.

Map your own database to the same states. Before placing any order, write a row with status placing and a timestamp. If your process crashes and restarts, that in-flight row tells you to check whether the order exists before retrying. For an introduction to the order API and event model, see Wholesale Gift Cards: REST API and Webhooks Explained.

Three categories of failure

  • Transient (5xx, timeout, connection reset): the request may or may not have arrived. Safe to retry only with an idempotency key.
  • Client error (4xx): the request is invalid. Do not retry without fixing the payload.
  • Ambiguous (0-byte body, TCP reset mid-response): treat the same as transient — safe to retry only with an idempotency key.

Step 2: Add an Idempotency Key to Every Order

An idempotency key is a unique string you generate before sending a request and pass in the Idempotency-Key request header — any unique visible-ASCII string up to 255 characters, for example a UUID. If FazerCards receives two requests carrying the same key within the deduplication window, it returns the order created by the first — no second charge, no duplicate code. The header is opt-in: without it every request creates a new order, because resellers legitimately place identical orders for different buyers. The API reference lists the order endpoints that accept it.

The key must be unique per logical order, not per HTTP attempt. Build it from your internal order ID and a short prefix — something like order-7841-v1. Persist it to your database before making the first request. On every retry, send the same key. The API guarantees idempotent behaviour.

Rules for a reliable key

  • Generate it once, before the first attempt, and save it immediately.
  • Never regenerate it on a new attempt — the key must be stable across retries.
  • Add a -v2 suffix only after you confirm the order genuinely failed and need a fresh placement.

With idempotency keys in place, an aggressive retry loop is safe: however many times you retry on a timeout, the API deduplicates on the key rather than on the HTTP connection.

Step 3: Implement Exponential Backoff with Jitter

A flat retry loop — three attempts, one second apart — amplifies load during any degraded period and still misses failures that resolve in fifteen seconds. Exponential backoff spreads the pressure and gives the upstream system time to recover.

A reliable pattern: wait 1 second before the first retry, 2 seconds before the second, 4 before the third. Add a small random jitter — 0 to 500 milliseconds — to each delay to prevent retry storms when many workers restart simultaneously. Cap the total attempts at four for synchronous order calls.

After all retries exhaust

Route the order to a dead-letter table in your database, fire an alert, and let a recovery job or on-call engineer inspect it. Never discard a failed order silently. If a partial response captured an order ID, call the order status endpoint to confirm whether the order exists before deciding to retry or refund. The API cookbook covers the recovery query pattern in detail.

Step 4: Verify Webhook Signatures

FazerCards notifies you about order events — a new order and every status change — via webhooks. Without signature verification, an attacker can POST a fake status event to your endpoint and push your system into acting on an order that never completed.

Each webhook request carries an X-Webhook-Signature header: the prefix sha256= followed by the hex HMAC-SHA256 digest of the raw request body, computed with your webhook secret. The webhooks reference has ready verification snippets in Node.js and Python. To verify, compute the same digest on your side using the raw bytes — before any middleware processes the body — and compare the result to the header value using a constant-time comparison function.

Why constant-time comparison matters

A standard equality check short-circuits at the first mismatching byte, leaking timing information that a patient attacker can exploit. A constant-time comparison — available in every major language standard crypto library — eliminates this side channel. Always use it when comparing HMAC digests.

If verification fails, return HTTP 401 and log the source IP. Never process the payload. A spike in failures on otherwise-legitimate traffic usually means a reverse proxy is re-encoding the body before it reaches your handler — read the raw bytes before any parsing layer touches them.

Step 5: Model Async Delivery as a State Machine

Some product categories — certain game top-ups and regional gift cards — are asynchronous: the API returns processing, and a webhook tells you minutes later that the status changed. The webhook body is deliberately minimal — the order ID and its status — so fetch the codes from the order endpoint with the same API key. These flows cannot be built as synchronous calls.

Structure your fulfilment logic as a state machine: placed → processing → webhook received → completed. Each state persists in a database row. A background worker monitors for orders stuck in processing beyond a product-specific threshold — five minutes for instant SKUs, thirty for async ones — and fires an alert when the threshold is crossed.

Do not block your customer-facing response on the order call. Accept the order, write the placing row, return an immediate confirmation to the customer, and push the code to the customer once the webhook arrives and you have fetched the completed order. This keeps your interface snappy regardless of upstream latency.

Step 6: Observe Order Health in Production

Three metrics should be live from day one. Placement success rate: successful POST responses divided by total placement attempts — below 99% warrants immediate investigation. Delivery rate: orders with a delivered code divided by successfully placed orders — below 98% usually signals a supply gap on a specific product. Webhook processing lag: the gap between the event timestamp inside the payload and your processed-at timestamp — a growing lag means your consumer is falling behind.

Cross-reference a delivery rate drop with the specific SKU before opening a support ticket. The FazerCards catalog shows live availability per category. Connect all three metrics to alerting thresholds: if any metric falls below its floor for ten consecutive minutes, page the on-call engineer.

What You Have Now

With idempotency keys preventing duplicate charges, exponential backoff absorbing transient failures, HMAC verification blocking forged delivery events, and a state-machine model handling async delivery, your integration covers the full failure surface of a real-world gift card operation. The question shifts from whether this will ever break to whether you will detect the breakage before the customer does — and at scale that gap translates directly into revenue.

Put every pattern to the test with a free 5-day Gold trial: full API and webhook access, 10,000+ products, no card and no KYC required. The trial runs on the same production API, so exercise your retry and idempotency logic with a few small orders before you scale to full batches.