Gift Cards & Promotions - Surfboard Payments

Overview

Surfboard Payments provides APIs for two complementary commerce features: gift cards for stored-value and entitlement-based programs, and promotions for marketing campaigns displayed across merchant channels. This guide covers creating and managing both, with full API details and request/response examples.

Gift Cards

Gift cards in Surfboard come in two types:

FUND — A stored monetary balance. Customers spend down the balance over one or more transactions.
ENTITLEMENT — A usage-limited card. Instead of a cash value, the card grants a fixed number of redemptions (e.g., “5 free coffees”).

Create a Gift Card

POST /gift-cards

FUND Type Request

{
  "cardType": "FUND",
  "amount": 500,
  "currency": "SEK",
  "name": "Holiday Gift Card",
  "accessControl": "OPEN",
  "expiryDate": "12/31/2026",
  "note": "Happy Holidays!"
}

ENTITLEMENT Type Request

{
  "cardType": "ENTITLEMENT",
  "redemptionLimit": 10,
  "name": "Loyalty Reward Card",
  "accessControl": "OPEN",
  "expiryDate": "06/30/2027",
  "note": "Thank you for being a valued customer"
}

Request Parameters

Parameter	Type	Required	Description
`cardType`	string	Yes	`FUND` or `ENTITLEMENT`
`amount`	number	Conditional	Monetary amount in smallest currency unit. Required for `FUND` type
`redemptionLimit`	number	Conditional	Number of allowed uses. Required for `ENTITLEMENT` type
`currency`	string	No	ISO currency code (e.g., `SEK`, `EUR`)
`name`	string	No	Display name for the gift card
`accessControl`	string	No	Access control level (e.g., `OPEN`)
`expiryDate`	string	No	Expiry date in `mm/dd/yyyy` or `mm-dd-yyyy` format
`note`	string	No	Optional note or message

Response

{
  "status": "SUCCESS",
  "data": {
    "giftCardId": "gc-abc-123",
    "pan": "6789012345678901",
    "name": "Holiday Gift Card",
    "cardType": "FUND",
    "amount": 500,
    "currency": "SEK",
    "accessControl": "OPEN",
    "status": "ACTIVE",
    "expiryDate": "12/31/2026",
    "shareableLink": "https://giftcards.surfboardpayments.com/gc-abc-123",
    "formats": {
      "qrCode": "data:image/png;base64,...",
      "nfcData": "NFC_ENCODED_DATA",
      "barcode": "data:image/png;base64,..."
    },
    "externalId": "ext-001",
    "externalIdType": "CUSTOM"
  },
  "message": "Gift card created successfully"
}

The response includes multiple format representations (QR code, NFC data, barcode) for flexible distribution. The shareableLink provides a URL that can be sent directly to the recipient.

List All Gift Cards

Retrieve a paginated list of all gift cards for a merchant, with optional filtering.

GET /gift-cards

Query Parameters

Parameter	Type	Required	Description
`type`	string	No	Filter by card type: `FUND` or `ENTITLEMENT`
`status`	string	No	Filter by card status

Response

{
  "status": "SUCCESS",
  "data": [
    {
      "giftCardId": "gc-abc-123",
      "pan": "6789012345678901",
      "name": "Holiday Gift Card",
      "cardType": "FUND",
      "amount": 500,
      "currentAmount": 350,
      "usageCount": 2,
      "currency": "SEK",
      "accessControl": "OPEN",
      "status": "ACTIVE",
      "expiryDate": "12/31/2026",
      "lastTransactionAt": "2026-01-15T14:30:00Z",
      "transactionCount": 2,
      "totalRedeemed": 150
    }
  ],
  "message": "Gift cards fetched successfully"
}

Note the tracking fields: currentAmount shows the remaining balance for FUND cards, usageCount tracks how many times the card has been used, and totalRedeemed shows the cumulative amount spent.

Get Gift Card Details

Retrieve full details for a single gift card, including customer information and format representations.

GET /gift-cards/:id

Response

{
  "status": "SUCCESS",
  "data": {
    "giftCardId": "gc-abc-123",
    "pan": "6789012345678901",
    "name": "Holiday Gift Card",
    "cardType": "FUND",
    "amount": 500,
    "currentAmount": 350,
    "usageCount": 2,
    "currency": "SEK",
    "status": "ACTIVE",
    "expiryDate": "12/31/2026",
    "lastTransactionAt": "2026-01-15T14:30:00Z",
    "transactionCount": 2,
    "totalRedeemed": 150,
    "customerDetails": {
      "customerId": "cust-456",
      "firstName": "Anna",
      "surname": "Svensson",
      "countryCode": "SE",
      "emails": [{ "email": "anna@example.com" }],
      "phoneNumbers": [
        {
          "phoneNumber": {
            "countryCode": "46",
            "number": "701234567"
          }
        }
      ]
    },
    "shareableLink": "https://giftcards.surfboardpayments.com/gc-abc-123",
    "formats": {
      "qrCode": "data:image/png;base64,...",
      "nfcData": "NFC_ENCODED_DATA",
      "barcode": "data:image/png;base64,..."
    }
  },
  "message": "Gift card details fetched successfully"
}

Get Gift Card Transactions

View the transaction history for a specific gift card. Supports filtering by transaction type and pagination via the x-page-number header.

GET /gift-cards/:giftCardId/transactions

Query Parameters

Parameter	Type	Required	Description
`transactionType`	string	No	Filter by type: `ISSUED`, `CREDIT`, or `DEBIT`

Response

{
  "status": "SUCCESS",
  "data": [
    {
      "paymentId": "pay-789",
      "transactionType": "DEBIT",
      "transactionAmount": 150,
      "currency": "SEK",
      "valueBefore": 500,
      "valueAfter": 350,
      "orderId": "order-456",
      "merchantId": "merchant-xyz-789",
      "storeId": "store-abc-123",
      "metadata": {}
    },
    {
      "paymentId": "pay-001",
      "transactionType": "ISSUED",
      "transactionAmount": 500,
      "currency": "SEK",
      "valueBefore": 0,
      "valueAfter": 500,
      "merchantId": "merchant-xyz-789",
      "metadata": {}
    }
  ],
  "message": "Transactions fetched successfully"
}

Each transaction record shows the valueBefore and valueAfter fields, giving a clear audit trail of the gift card balance over time.

Promotions

Promotions let you create and manage marketing campaigns that appear across merchant channels, such as on payment terminals, receipts, and idle screens. Each promotion is scoped to a specific merchant and store.

Create a Promotion

POST /merchants/:merchantId/stores/:storeId/promotions

Request

{
  "title": "Summer Sale",
  "name": "summer-sale-2026",
  "description": "50% off all summer items",
  "assetUrl": "https://cdn.example.com/promo-summer.png",
  "type": "RECEIPT_BIG",
  "assetOpacity": "0.8",
  "backgroundColor": "#1e3a5f",
  "contentTextColor": "#ffffff",
  "endProductUrl": "https://shop.example.com/summer",
  "endProduct": "SUMMER-COLLECTION",
  "buttonLabel": "Shop Now",
  "priority": 1,
  "startDate": "06-01-2026",
  "endDate": "08-31-2026"
}

Request Parameters

Parameter	Type	Required	Description
`name`	string	Yes	Unique name for the promotion
`type`	string	Yes	Promotion type (e.g., `RECEIPT_BIG`, `RECEIPT_SMALL`)
`priority`	number	Yes	Display priority. Lower numbers = higher priority
`startDate`	string	Yes	Start date in `MM-DD-YYYY` format
`endDate`	string	Yes	End date in `MM-DD-YYYY` format
`title`	string	No	Display title for the promotion
`description`	string	No	Brief description of the promotion
`assetUrl`	string	No	URL of the promotional image
`assetOpacity`	string	No	Image opacity, `0` (transparent) to `1` (opaque)
`backgroundColor`	string	No	Background color in hex format
`contentTextColor`	string	No	Text color in hex format
`endProductUrl`	string	No	URL of the promoted product
`endProduct`	string	No	Product ID linked to the promotion
`buttonLabel`	string	No	Label for the call-to-action button

Response

{
  "status": "SUCCESS",
  "data": {
    "promotionId": "promo-abc-456"
  },
  "message": "Promotion created successfully"
}

List All Promotions

Retrieve all promotions for a merchant’s store to view, manage, and track active and past campaigns.

GET /merchants/:merchantId/stores/:storeId/promotions

Response

{
  "status": "SUCCESS",
  "data": [
    {
      "promotionId": "promo-abc-456",
      "merchantId": "merchant-xyz-789",
      "storeId": "store-abc-123",
      "name": "summer-sale-2026",
      "title": "Summer Sale",
      "description": "50% off all summer items",
      "assetUrl": "https://cdn.example.com/promo-summer.png",
      "endProduct": "SUMMER-COLLECTION",
      "buttonLabel": "Shop Now",
      "startDate": "2026-06-01T00:00:00Z",
      "endDate": "2026-08-31T00:00:00Z",
      "priority": "1",
      "assetOpacity": "0.8",
      "backgroundColor": "#1e3a5f",
      "contentTextColor": "#ffffff",
      "endProductUrl": "https://shop.example.com/summer"
    }
  ],
  "message": "Promotions fetched successfully"
}

Get Promotion by ID

Retrieve the full configuration and current state of a single promotion.

GET /merchants/:merchantId/stores/:storeId/promotions/:promotionId

The response structure is identical to a single item in the list response above.

Update a Promotion

Modify any attributes of an existing promotion. Send only the fields you want to change.

PUT /merchants/:merchantId/stores/:storeId/promotions/:promotionId

Request

{
  "description": "Up to 60% off all summer items - extended!",
  "endDate": "09-30-2026",
  "priority": 1
}

All fields are optional. The response confirms the update:

{
  "status": "SUCCESS",
  "message": "Promotion updated successfully"
}

Delete a Promotion

Permanently remove a promotion and its associated data.

DELETE /merchants/:merchantId/stores/:storeId/promotions/:promotionId

Response

{
  "status": "SUCCESS",
  "message": "Promotion deleted successfully"
}

Warning: Deletion is permanent. The promotion will no longer be active or visible on any channel.

API Quick Reference

Operation	Method	Endpoint
Create gift card	POST	`/gift-cards`
List all gift cards	GET	`/gift-cards`
Get gift card details	GET	`/gift-cards/:id`
Get gift card transactions	GET	`/gift-cards/:giftCardId/transactions`
Create promotion	POST	`/merchants/:merchantId/stores/:storeId/promotions`
List all promotions	GET	`/merchants/:merchantId/stores/:storeId/promotions`
Get promotion by ID	GET	`/merchants/:merchantId/stores/:storeId/promotions/:promotionId`
Update promotion	PUT	`/merchants/:merchantId/stores/:storeId/promotions/:promotionId`
Delete promotion	DELETE	`/merchants/:merchantId/stores/:storeId/promotions/:promotionId`

Store Management

Product Catalog

Ready to get started?

Create a sandbox account and start building your integration today.

Create Sandbox Account All Guides