Skip to main content

POS Gift Cards

This page documents the gateway-side shape POS must mirror for gift-card redemption and refund flows.

Related sign-off thread: pinpointpos/monorepo#999 (T12).

Runtime boundary​

POS does not call the public merchant OAuth surface for card-present gift-card redemption. It uses the internal gift-card lane:

  • InternalGiftCardsApi.redeem(...)
  • InternalGiftCardsApi.refund(...)

Those endpoints map to processing-service internal routes and are intended for service-to-service callers such as POS and online-txn.

Current launch behavior​

TopicCurrent behavior
Scope modelGift cards are organization-scoped
Redemption across locationsAllowed within the same organization
Location restriction enforcementNot enforced at redemption time today
FX / mixed-currency redemptionNot supported
Number-prefix / number-length configEffectively platform-admin-only today
Refund fallback when card credit cannot be restoredImplemented via reroute to the primary tender

That location-restriction row is the one concrete runtime mismatch the docs keep explicit. Everything else in this table reflects current runtime behavior.

Auth and IAM requirements​

The required auth shape is:

  1. Cloud Run IAM grants the caller service account invoke access to the internal service.
  2. The request is authenticated as an internal service caller.
  3. Gateway sees ROLE_INTERNAL_SERVICE on the request and permits the internal gift-card endpoints.

In local-dev and gateway smoke tests, InternalServiceClient supplies the internal-caller header that the gateway's local-dev auth path accepts. In staging/production, that same caller must present the Google-signed IAM identity token for the target service URL.

This is intentionally different from the public portal or merchant API flow. A Firebase user token or ordinary OAuth merchant token is not enough for these endpoints.

Expected redemption flow​

  1. POS identifies the current location and transaction.
  2. POS calls InternalGiftCardsApi.redeem(...) with:
    • locationId
    • amountCents
    • transactionId
    • idempotency key derived from the POS ticket
  3. Gateway validates that the gift card’s organization matches the transaction location’s organization.
  4. Gateway writes the ledger mutation and returns the resulting balance.

Refunds follow the same internal-service pattern through InternalGiftCardsApi.refund(...).

Location restrictions​

Gift-card location restrictions are enforced at redemption time.

In practice that means:

  • a card can still be redeemed across locations in the same organization by default
  • once a location is marked restricted for that organization, redemption from that location is rejected by the gateway with a gift-card validation error

Integration implication:

  • POS can rely on the gateway to block redemption from restricted same-org locations
  • if product wants a different allowlist model later, that is a policy change, not a missing enforcement gap

Currency behavior​

Gift-card redemption and reload flows are same-currency only. There is no gateway-side FX conversion path during redemption, reload, or refund-to-card.

Integration implication:

  • POS should not offer a cross-currency gift-card redemption path and expect the gateway to convert values
  • if a tender mix spans currencies, resolve that in product design before assuming the gateway can settle it

Numbering and config ownership​

Gift-card configuration supports number-prefix and number-length fields, but the management proxy strips those fields from ordinary merchant-managed updates. As shipped today, custom numbering should be treated as a platform-admin-managed operation, not a self-serve merchant or POS capability.

Refund reroute behavior​

If a refund cannot restore value to the original gift card because the card is REVOKED or EXPIRED, the gateway reroutes that allocation back to the primary tender instead of silently dropping value.

See Gift Card Webhook Events for the related eventing and observability behavior.

Not promised at launch​

The following should still be treated as unavailable unless and until runtime behavior changes:

  • enforcing gift_card_location_restrictions during redemption
  • a separate gift-card transfer endpoint
  • Apple Wallet or Google Wallet gift-card passes

Safe launch claims​

Support, solutions, and integrators can safely describe the current gift-card lane like this:

  • gift cards are organization-scoped
  • redemption works across locations in the same organization
  • custom numbering is not a normal merchant self-serve feature
  • FX conversion is not part of redemption or refund
  • refund value reroutes to the primary tender if the original card cannot take it

They should not describe the current lane as:

  • same-location-only redemption enforced by the gateway
  • transfer-capable between cards
  • wallet-pass enabled for Apple Wallet or Google Wallet

Docs-side closeout checklist​

Treat the gift-card lane as documentation-complete for #651 only if all of the following are true:

  • launch materials describe gift cards as organization-scoped
  • same-org cross-location redemption is documented as allowed only when the organization has not restricted the redeeming location
  • gift_card_location_restrictions is called out as a runtime enforcement mechanism, not just a modeled table
  • wallet passes, transfer flows, and FX conversion remain listed as non-promises instead of implied launch features

Validation coverage​

Gateway keeps a dedicated smoke test for this path:

  • //services/processing:pos_gift_card_smoke_integration_test

Run it manually with:

  • bazel test //services/processing:pos_gift_card_smoke_integration_test

That test exercises:

  • gift-card issuance setup on the gateway side
  • cross-location redemption inside one organization
  • idempotent retry
  • refund back onto the card
  • webhook emission for redeem/refund
  • the loopback InternalServiceClient -> InternalGiftCardController -> GiftCardService path POS mirrors in production

The target is tagged manual because POS release validation invokes it on demand rather than in the default suite.