Gift cards resource guide

What this resource is for

This resource is used to offer and issue digital gift cards, and to check the balance on a card that has been issued. It supports funding from a prepaid publisher balance or from a hosted payment page.

When to use it

• Use giftCardRequestApi when you hold a prepaid float with Spendstream.
• Use paymentLink (see Payments) when customers pay through the Spendstream hosted page.
• Use giftCardBalanceCheck to show the remaining value on an issued card.
• Use postGiftCardRequest only if your integration has been set up to fulfil from an order held in your own database. Most integrations should not.

Important implementation notes

• promo_id is the promotion-id from getPromotionsList. It is not the brand-id. A brand identifier returns a 400 error with “no promotion found connection”.
• There is no server-side idempotency. Record the order on your side first and deduplicate. Do not rely on the Idempotency-Key header.
• Validate brand availability, permitted values, publisher balance, recipient information and duplicates before you submit.
• Treat fulfilment as successful only when Spendstream returns a confirmed order result, and confirm with TRANSACTION_UPDATED.
• Check your balance before submitting a prepaid order. checkPBalance may be permission gated for your account.
• Staging is sandboxed end to end. No real money or float is used.
• Digital gift cards are generally non-refundable once issued.

 
curl -X POST "https://staging-api.spendstream.io/v2/giftCardBalanceCheck" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "User-Agent: YourApp/1.0" \
  -d '{"...": "see the API reference for the request fields"}'

Common mistakes

• Sending a brand-id as promo_id.
• Retrying a timed-out order without first checking whether it was issued.
• Treating a success page as safe to reload. A repeat visit to a paid order is rejected, but a narrow timing overlap is still being hardened.
• Submitting without checking the balance.

Related resources

• Promotions
• Payments
• Balances
• Transactions
• Gift cards product guide

Endpoint reference

The v2 endpoints for this resource are giftCardRequestApi, postGiftCardRequest and giftCardBalanceCheck. Exact parameters, schemas and responses are in the API reference.