Skip to main content

POS Gift Cards

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

Runtime boundary

POS redeems gift cards through the normal merchant OAuth surface on the pay host:

  • GatewayPayClient.payGiftCards.redeem(...)
  • GatewayPayClient.locations.redeemGiftCard(...)
  • GatewayPayClient.locations.refundGiftCard(...)

Those SDK methods call pay-host routes under /api/v1/gift-cards/... or /api/v1/locations/{locationId}/gift-cards/... with the caller's Gateway OAuth token. The token requires gift_cards:write and authorization for the requested location/organization.

Current behavior

TopicCurrent behavior
Scope modelGift cards are organization-scoped
Redemption across locationsAllowed within the same organization
Location restriction enforcementEnforced through the per-organization location deny list
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

Auth requirements

The required auth shape is:

  1. POS uses a Gateway OAuth access token that includes gift_cards:write.
  2. The token must be location-scoped to the requested location or organization-scoped to that location's organization.

Expected redemption flow

  1. POS identifies the current location and transaction.
  2. POS calls GatewayPayClient.locations.redeemGiftCard(...) 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 use a location-scoped route through GatewayPayClient.locations.refundGiftCard(...).

Connected POS customer display

On Peak POS, the cashier selects Pay with Gift Card and scans or enters the card even when a customer display is connected. The customer display shows the amount applied and the remaining due; gift-card entry stays on the cashier screen. Apply the gift card first, then collect any remainder with cash, card, or the existing split-payment flow (cash before card).

The customer display's Cash, Card, and Split choices remain available for the unpaid remainder. A gift-card sale/load item cannot itself be paid with a gift card, and tender still requires an authoritative checkout quote.

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
  • a different allowlist model 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.

Unsupported current behavior

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

  • a separate gift-card transfer endpoint
  • Apple Wallet or Google Wallet gift-card passes