---
locale: en
translated: true
title: "What a gift card balance can and cannot prove"
url: https://insightlog.site/en/posts/gift-card-api-risk-model
site: "InsightLog"
published: 2026-11-05T09:50:16.986Z
updated: 2026-11-20T09:50:16.986Z
author: "Sofia Almeida"
author_url: https://insightlog.site/en/authors/sofia-almeida
type: "Analysis"
category: "Gift Cards"
tags: ["Gift Cards", "Payments", "Fraud Prevention", "API"]
reading_minutes: 1
views: 626
upvotes: 26
downvotes: 0
---
## A balance is a liability, not a receipt

Gift cards look simple: load value, spend value. In production, a balance is a **liability entry**, not proof of payment. Two questions get mixed together:

1. Was the value issued?
2. Was the cash collected and settled?

An API that only answers the first question cannot support finance, disputes or fraud review.

## Separate the four events

| Event | Question it answers | Mutates balance |
| --- | --- | --- |
| Issuance | Was a card created? | No |
| Activation | Is the card usable? | Yes |
| Redemption | Was value spent? | Yes |
| Settlement | Did the cash arrive? | No |

When these events share one endpoint, a failed settlement looks identical to an unactivated card.

## Idempotency is the security control

Every redemption call needs a client-generated idempotency key. Without one, a retry after a network timeout can double-spend a card. Store the key next to the resulting ledger entry and return the original response when the key repeats.

## What to expose

- A signed balance snapshot with currency, as-of time and event id.
- A ledger endpoint filtered by card and time range.
- A redemption endpoint that returns both the new balance and the ledger entry id.

Never expose internal card numbers or full primary account numbers. Use tokenized references and scope them per merchant.

## Red flags in review

1. Balance overwrites instead of append-only ledger entries.
2. Redemption endpoints that succeed twice for the same key.
3. No link between activation batches and settlement batches.
4. Timestamps without a timezone.

## Conclusion

Treat a gift card as a small financial ledger. The API is trustworthy when every balance change has an event, an idempotency key and an audit trail.
