Gift Card API Explained: What Finance & Dev Teams Actually Need to Know

What a Gift Card API Does (and What Most Vendors Won't Tell You)

A gift card API abstracts the operational complexity of sourcing, fulfilling, and reconciling digital gift cards across retail brands. Instead of managing vendor integrations, SKU databases, inventory, and settlement workflows yourself, the API handles it—and passes results back through webhooks, bulk exports, or a dashboard.

But here's what vendors skip over: an API is only as useful as the infrastructure behind it. You need:

• Catalog breadth — enough brands across the geographies your customers actually live in.
• Settlement speed — money in your bank account in days, not weeks.
• Reporting granularity — transaction-level data your finance team can reconcile against your GL.
• Webhook reliability — real-time, signed event notifications with a documented retry policy.
• Security posture and compliance — PCI Level 1, SOC 2 Type II, and audit logs that survive a regulator review.
• Pricing transparency — one quote that includes FX, settlement, and any hidden processing fees.

Most vendors win on one or two of these. Few win on all six. That's where most teams stumble during evaluation.

‍

The 6 Buy Criteria Most Teams Get Wrong

1. Catalog Breadth: Size Matters, but Geographic Coverage Matters More

A vendor might claim 400+ brands. If 300 are US-only and you operate in Europe, you've got a 100-brand catalog in practice. Ask specifically:

• How many brands are available in each of your top three target countries — not just "globally"?
• Do they offer local-currency cards, or only USD/EUR cards that the recipient has to convert?
• How frequently is the catalog updated, and how are brand outages communicated?
• What's the mix of digital-only versus physical/plastic, and does that match how your recipients want to redeem?

Why it matters: A narrow catalog is a dead end for your users. They'll switch platforms. If your vendors' catalog can't scale with your geography, you'll hit a ceiling.

2. Settlement Speed: Days to Cash, Not Months

T+1 (next business day) is table stakes. Anything slower is a cash flow drag. But there's a catch: some vendors T+1 to an escrow account, not your actual bank. Ask for:

• Settlement directly to your operating bank account, with the actual cut-off times in your timezone.
• Whether funds sit in an escrow or holdback account before they're released — and for how long.
• Volume or risk thresholds that trigger longer holds (some vendors silently switch you to T+7 once you cross a number).
• A written remittance schedule and reconciliation file you can hand to your accounting team.

Why it matters: Slow settlement inflates your working capital needs. If you're processing $10K daily and settlement is T+30, you're sitting on $300K of float.

3. Reporting Granularity: Can You Reconcile Automatically?

A CSV dump at end-of-day is not reconciliation-grade reporting. You need:

• Transaction-level records with timestamps, idempotency key, brand, denomination, currency, and your internal reference ID on every row.
• A reconciliation API endpoint you can query at any time — not a daily file you have to wait for.
• Clear status fields (pending, fulfilled, refunded, failed) so you can map each line to its GL state without manual intervention.
• An audit trail for refunds, cancellations, and chargebacks — including who initiated them and when.

Why it matters: If your finance team spends 4 hours weekly reconciling gift card transactions, your API chose complexity over clarity. Reconciliation should be 30 minutes of spot-checking, not 4 hours of detective work.

4. Webhook Reliability: Trust the Notification, or Build Redundancy

Webhooks are how you know a transaction succeeded in real-time. Unreliable webhooks force you to poll. Polling is expensive and slow. Ask:

• What's the published webhook delivery SLA (e.g. 99.9% within 60 seconds)?
• What's the retry policy on failures — exponential backoff, max attempts, dead-letter queue?
• Are webhooks signed (HMAC) so you can verify they really came from the vendor?
• What's the historical delivery rate over the last 90 days, and will they share an uptime page?
• Do they alert you when a webhook endpoint is failing, or do you have to discover it yourself?

Why it matters: A 99% webhook delivery rate sounds great until you process 10K transactions daily and 100 go missing each day. That's 36K lost transactions yearly. You'll need to build polling logic as a fallback, which doubles your integration cost.

5. Security Posture & Compliance: PCI Scope, Audit Logs, and Data Handling

Ask these directly:

• Are you PCI DSS Level 1 certified, and can you share the most recent AOC?
• Do you have a SOC 2 Type II report, and how recent is it?
• How long are audit logs retained, and can we query them via API?
• What's your incident response timeline — when would we be notified of a breach affecting our data?
• Where is data stored, and do you offer data residency options for EU/UK customers?

Why it matters: If your vendor isn't PCI Level 1, regulatory fines land on you, not them. If audit logs don't exist, you can't prove data wasn't accessed during a breach.

6. Pricing Transparency: Revenue Share vs. Flat Fee vs. FX Markup

This is where vendors obscure the most. Typical models:

• Revenue share / commission split — vendor keeps 25–35% of the spread between face value and your sale price.
• Flat fee per transaction — fixed per-card cost (e.g. $0.20), sometimes plus a small percentage.
• FX markup — 2–4% added to international transfers, often quoted separately or buried in T&Cs.
• Hidden ancillaries — escrow fees, processing fees, monthly platform fees, brand-tier surcharges.

Model your expected volume through each vendor's pricing. The cheapest per-transaction rate often isn't the cheapest overall.

Why it matters: A vendor quoting $0.15/transaction and also taking 2% FX markup is more expensive than one quoting $0.20/transaction with no markup. Always model net cost.

‍

Self-Serve Bulk vs. API: When Each Makes Sense

Not every business needs an API. Some need a bulk self-service tool. Know the difference:

‍

Use bulk if: You're a finance team running quarterly gift card programs. Velocity is low, operational burden is acceptable.

Use API if: You're embedded in a customer-facing product (marketplace, rewards platform, payroll app). Your users expect instant fulfillment. Reconciliation at scale requires automation.

Many teams start with bulk and migrate to API once order volume exceeds 500/month. Plan your vendor choice accordingly—does their platform support both, or will migration force a painful switch?

‍

Implementation Timeline: From Kickoff to First $1

Realistic phases:

Phase 1: Vendor Evaluation & Contract (2–4 weeks)

• Run a structured RFI/RFP against 2–3 shortlisted vendors using the six criteria above.
• Get sandbox access early — many evaluation gaps only show up once you actually call the API.
• Negotiate contract terms in parallel: pricing model, settlement timing, SLAs, data residency, termination clauses.

Phase 2: Sandbox & Development (2–6 weeks)

• Build your integration against the sandbox: order creation, webhook receivers, idempotency, error handling, refunds.
• Wire up reconciliation: pull the daily settlement file or reconciliation endpoint into your accounting system.
• Run load and edge-case tests — duplicate orders, timeouts, retries, brand outages, currency mismatches.

Phase 3: UAT & Production Ramp (1–2 weeks)

• Run end-to-end UAT with real cards in production at low volume (10–50 transactions).
• Roll out to 10%, then 50%, then 100% of traffic, monitoring webhook delivery, settlement, and refund flows at each step.
• Set up alerting on stuck states, missed webhooks, and failed reconciliations before you walk away from the project.

Total: 5–12 weeks from contract to first live transaction. The variance depends on engineering capacity, vendor responsiveness, and how complex your reconciliation logic is.

Pro tip: Run parallel workstreams. While legal negotiates, start sandbox development. While dev integrates, finance models pricing and creates reconciliation specs.

‍

Reconciliation, Webhooks, and Idempotency

This is where most teams underestimate complexity.

Idempotency: Never Double-Charge a Customer

If your API call times out, did the card order go through? You don't know. So you retry. If you retry without idempotency keys, you've now ordered the card twice.

How it works:

POST /api/v1/orders
{
"idempotency_key": "cust_12345_order_789_ts_1681234567",
"customer_id": "cust_12345",
"brand_id": "AMAZON_US",
"amount": 50,
"currency": "USD"
}

The idempotency key is unique per order request. If the vendor receives the same key twice (e.g., your app retries), they return the original response without charging again. This is industry standard.

Implementation: Generate idempotency keys as customer_id_order_id_timestamp or use a UUID. Vendors must support this. If they don't, escalate—it's a dealbreaker.

Webhook Verification: Cryptographic Signing

An attacker could send a fake webhook claiming "your payment was received" when it wasn't. Verify signatures.

// Vendor sends webhook with X-Signature-256 header
// You verify:

const crypto = require('crypto');
const body = JSON.stringify(req.body);
const signature = req.headers['x-signature-256'];
const expected = crypto
.createHmac('sha256', WEBHOOK_SECRET)
.update(body)
.digest('hex');

if (signature === expected) {
// Webhook is authentic, process it
} else {
// Reject, log, alert
}

Every vendor should provide a webhook secret. Use it. Every time.

Reconciliation: The Golden Record

Your system of record is not the vendor's dashboard. It's your database.

Daily reconciliation flow:

1. Pull the vendor's reconciliation report (or query the reconciliation API) for the previous 24 hours.
2. Match every vendor transaction to a row in your internal orders table by idempotency key.
3. Flag any vendor record that doesn't match an internal order — these are usually missed webhooks.
4. Flag any internal order with no matching vendor record — these are usually failed orders that need a refund or retry.
5. Compare totals (count and dollar value) and post the day's clearing entry to your GL.
6. File exceptions to your finance queue with enough context (order ID, recipient, amount, vendor status) to investigate.

Use the vendor's reconciliation-grade API for this, not webhooks alone. Webhooks can fail or arrive out of order. An API query is the source of truth.

‍

Security, Compliance, and Data Handling

‍

PCI DSS Scope: Keep Cards Off Your Systems

If you store, process, or transmit card numbers, you're in PCI scope. PCI compliance is expensive (penetration testing, security audits, regular assessments).

The goal: tokenization. You never see the actual card number.

Flow:

1. Your app calls the vendor API to create an order, passing customer details and amount — no card data.
2. The vendor generates the gift card code on their PCI-certified infrastructure.
3. The vendor delivers the code directly to the recipient (email, SMS, or hosted redemption URL) — your servers never touch it.
4. You receive a token or order ID back so you can track redemption status without ever handling the actual card number.

This keeps you out of PCI scope. Confirm your vendor supports this model.

‍

Audit Logs: Who Accessed What and When

If a breach happens, regulators will ask: "Who accessed customer data?" Audit logs are the answer.

You should be able to query:

• Which user (or API key) accessed which transaction record, and when.
• Which transactions were modified, refunded, or cancelled, and by whom.
• Which webhook endpoints received which events, and the delivery status.
• Login activity and permission changes on the vendor dashboard, scoped to your account.

Vendors should retain these for at least 12 months. If they don't offer audit logs, they're not enterprise-ready.

Data Retention & Deletion Policies

Ask:

• How long is recipient PII retained after a transaction completes?
• What's the process — and SLA — for honoring a GDPR or CCPA deletion request?
• Are backups also purged, or only the primary database?
• Can you specify data residency (EU-only, US-only) at the account level?

If they can't answer these, they don't have a mature compliance program.

‍

Pricing Models: Revenue Share vs. Flat Fee vs. FX Markup

‍

Revenue Share (Most Opaque)

Model: Vendor takes 25–35%, you get 65–75% of the spread between your sales price and the card's cost.

Example: You sell a $50 Amazon card for $52 (customer pays $52, you keep spread + commission). Card costs vendor $47. Spread is $5. If you get 70%, you pocket $3.50, vendor keeps $1.50.

Pros: Upside if you negotiate premium prices.

Cons: You never know true unit cost. Spreads vary by brand and time, so your margin is unpredictable.

Best for: High-volume, high-margin businesses where you're willing to trade cost transparency for negotiated percentage.

‍

Flat Fee (Most Transparent)

Model: Fixed cost per card. E.g., $0.20 per card, or $0.15 + 1.5% of value.

Example: You sell 1K Amazon cards at $50 each. Cost: 1K × $0.20 = $200. You keep ($52 × 1K) − $200 = $51,800 revenue.

Pros: Predictable, auditable, scales well with volume.

Cons: Per-transaction fees can be high at low volumes. Less negotiation room.

Best for: B2B platforms, API-driven, high volume, need predictable COGS.

‍

FX Markup (Hidden Tax on International)

Model: Vendor adds 2–4% to international transfers.

Example: You send $1,000 USD to a UK customer. Vendor applies 2.5% markup. Customer receives GBP equivalent of $1,025. Vendor pockets $25.

Pros: None, for you.

Cons: Hidden. Erodes margins on international orders. Hard to model in pricing.

Gotcha: Some vendors quote $0.15/card but don't mention FX markup. Model the full transaction including FX before comparing.

‍

Gift Card API Vendor Comparison

‍

How to Read This Table

Enterprise incumbent: Industry standard, established. Good for domestic US programs. Settlement is slower than GIFQ. Revenue share model makes cost modeling harder.

UK-based payout platform: Strong for payroll integration. Higher costs due to FX markup on international. Best if you're already in their partner ecosystem.

Giftbit: Simple, affordable, good for SMBs. Limited global reach and weaker webhook reliability make it harder to scale.

GIFQ: Built for global, API-first businesses. Advantage: no FX markup (transparent cost), T+1 to real bank account (better cash flow), largest global catalog. Designed for reconciliation automation from day one. Trade-off: less brand recognition than the incumbents; smaller partner ecosystem (but growing).

Bottom line: Pick based on geography (US-only vs. global), volume (low vs. high), and integration model (bulk vs. API). There's no universal "best"—only the best fit for your use case.

‍

Your Next Steps

1. Audit your current needs: How many countries do you operate in? What's your monthly transaction volume? Do you need webhooks or bulk is fine?

2. Score vendors on the 6 criteria: Use this rubric with your eng and finance teams. Don't weight all 6 equally—rank them by your constraints.

3. Model pricing at volume: Get quotes from 2–3 vendors. Calculate true cost (flat fee + FX markup + settlement float) at 3 volume levels (1K, 10K, 100K transactions).

4. Request sandbox access: Have your eng team spend a week building a test integration. If the API is painful or webhooks are unreliable, you'll know quickly.

5. Finalize your decision: Cost matters, but reliability and coverage matter more. The cheapest vendor that can't deliver is useless.

If you're evaluating options, we're here to help. Talk to our sales team about how GIFQ stacks up for your use case.