Gift Card Infrastructure, Not a Gift Card Product
One API to issue, distribute, and redeem gift cards. Two distinct card types — monetary balance or usage-based entitlement. Multi-format payloads in every response so your platform meets customers wherever they are. Your brand, your campaigns, our infrastructure.
Two Card Types. One Coherent API.
Most gift card APIs only model monetary value. Surfboard models two — FUND for cards backed by an amount, and ENTITLEMENT for cards backed by a count of redemptions. The latter is what unlocks class passes, meal allowances, punch cards, and bundled experiences inside the same API surface.
Both card types ship with QR, barcode, NFC, and shareable-link encodings out of the box. Both compose with the Identification API, the Payments API, and the Branding API. Both are issued, redeemed, and tracked through the same flat endpoint surface.
Built for partners, not for end-merchants
The Gift Cards API is infrastructure. POS partners, loyalty platforms, HR benefits providers, and ticketing systems integrate it and present gift cards under their own brand. Surfboard handles issuance, encoding, redemption, and reconciliation — your platform handles the customer.
How It Works — 3 Steps
Issue a gift card via API
POST /giftcards
{
"cardType": "FUND",
"amount": 50000,
"currency": "SEK",
"name": "Holiday Gift Card",
"accessControl": "OPEN",
"expiryDate": "12/31/2026"
}
Distribute the card in any format
{
"giftCardId": "83a5aea0381600045c",
"pan": "1504703347938280",
"formats": {
"qrCode": "...",
"nfcData": "...",
"barcode": "2877866156"
},
"shareableLink": "https://slr.surfboardpayments.com/afaa6fb5"
}
Redeem and track usage
GET /giftcards/:giftCardId/transactions
// Returns full redemption history per card
What you can build
Two card types and four output formats compose into a surprisingly wide range of products. Here are the patterns that come up most often.
1. Monetary Gift Cards (FUND type)
The classic gift card. Issue with a fixed monetary amount and currency. Customers tap, scan, or share the code to spend down the balance over multiple transactions.
- Fixed denomination or partner-defined amount
- Multi-currency support
- Partial redemption with running balance
- Configurable expiry
Perfect for:
- Retail seasonal campaigns
- Refunds issued as store credit
- Employee perks and corporate gifting
2. Usage-Based Entitlements (ENTITLEMENT type)
Less common, more powerful. ENTITLEMENT cards represent a number of redemptions, not an amount. Each tap or scan counts down the remaining usage.
Useful for:
- Class passes (10-pack yoga, gym, padel)
- Meal entitlements (subsidized canteens, school lunches)
- Event punch cards (festivals, conferences)
- Coffee subscription cards (every 5th drink free)
- Healthcare visit allowances
3. Multi-Format by Default
Every gift card returns three encoded formats and a shareable link in one response — no second integration, no third-party generator.
- QR code — for app-based and customer-display flows
- Barcode — for receipt printing and legacy scanners
- NFC data — for tap-to-redeem on Surfboard terminals
- Shareable link — for email, SMS, Messenger distribution
Pick whichever format fits your channel. Customers don't care, and they don't have to.
4. Open or Restricted Access
Choose OPEN for cards anyone can redeem (classic retail gift card behaviour) or RESTRICTED for cards tied to a specific holder (corporate benefits, member entitlements, employee perks).
Restricted cards combine naturally with Identification for tap-to-claim flows that don't require an app.
5. External ID Linkage
Every card carries an externalId and externalIdType field — your own system's identifier for the card, the holder, the campaign, or the order it was issued against.
No reconciliation pain. Every gift card transaction back-references your own model.
6. Infrastructure, Not a Gift Card Product
Surfboard provides the rails — issuance, encoding, redemption, transaction history. Your platform owns the customer experience, the campaign creative, the merchant-facing UI.
POS partners, loyalty platforms, and HR-tech vendors integrate the API and ship gift cards under their own brand. Surfboard never appears.
Every card, four formats, one response
Scan from screen, redeem at terminal.
Print on receipts, vouchers, or physical cards.
Tap-to-redeem on any Surfboard device.
Distribute over email, SMS, or chat.
Composes with the rest of the platform
RESTRICTED gift cards combine with the Identification API for tap-to-claim flows. Card transactions write to the same Reporting layer your settlements come from. Every encoding format works on every Surfboard terminal already in the field.
Gift cards aren't a side-product. They're a first-class object in the platform.
Issue your first gift card
Four endpoints cover the full lifecycle — create, fetch all, fetch by ID, fetch transactions. Multi-format encoding and shareable links come back on creation, no second call.
// Create a 10-class yoga pass as an ENTITLEMENT card
POST /giftcards
{
"cardType": "ENTITLEMENT",
"redemptionLimit": 10,
"name": "Yoga 10-Pack",
"accessControl": "RESTRICTED",
"expiryDate": "12/31/2026"
}
// Response includes every encoding format
{
"status": "SUCCESS",
"data": {
"giftCardId": "83a5aea0381600045c",
"pan": "1504703347938280",
"formats": {
"qrCode": "...",
"nfcData": "...",
"barcode": "2877866156"
},
"shareableLink": "https://slr.surfboardpayments.com/..."
}
}