Gift card product guide

Spendstream lets your customers buy digital gift cards from more than 150 major brands. Cards are supplied by our gift card supplier and issued digitally once the order is confirmed.

How gift cards work

There are two ways to fund a gift card order, and your publisher account is set up for one of them.

Gift cards can be shown in your own interface or through the Spendstream white-label platform.

The purchase flow

 
flowchart TD
    A[Get token] --> B[Add or find user]
    B --> C[List promotions]
    C --> D[Customer picks a card]
    D --> E{Funding model}
    E -->|Hosted payment| F[Call paymentLink]
    F --> G[Customer pays on hosted page]
    G --> H[Spendstream issues card]
    E -->|Prepaid balance| I[Call giftCardRequestApi]
    I --> H
    H --> J[TRANSACTION_UPDATED webhook]

Key points to get right

1. promo_id is the promotion-id. Take it from getPromotionsList. Do not send the brand-id from getBrands. A brand identifier returns a 400 error with the message “no promotion found connection”.
2. Treat an order as successful only when Spendstream confirms it. For hosted payments, that means the TRANSACTION_UPDATED webhook or a confirmed transaction record. A customer returning to your site is not proof of payment.
3. There is no server-side idempotency. Spendstream does not de-duplicate orders for you. Record each order on your side before you submit it, and never resubmit blindly after a timeout.
4. Avoid refreshing the payment success page. A repeat visit to a paid order is rejected, but a narrow timing overlap is still being hardened.
5. Validate user_id yourself.paymentLink creates an unknown user_id with blank details rather than rejecting it, so a typo produces a new empty user.
6. Digital gift cards are generally non-refundable once issued, subject to your agreement and legal requirements.

⚠️ Warning: Do not rely on the Idempotency-Key header to prevent duplicate orders. Deduplicate on your own side.

Testing

Staging is sandboxed from end to end. No real money or float is used, and vouchers are issued on a sandbox site. See the testing guide for test cards and the special amounts that force declines.

Related pages

• Gift Cards resource guide
• Payments resource guide
• Balances resource guide
• Promotions resource guide