Hosted payment model

For gift cards, Spendstream can take payment for you on a hosted payment page. Your customer pays on that page, so card details never pass through your servers.

How it works

You call paymentLink to create a payment for a promotion and a user. The response contains a link to a hosted payment page provided by our payment provider. You send the customer to that link. When payment succeeds, Spendstream issues the gift card through its gift card supplier and sends a TRANSACTION_UPDATED webhook to your endpoint.

 
sequenceDiagram
    participant C as Customer
    participant P as Your product
    participant S as Spendstream
    participant G as Payment page
    C->>P: Chooses a gift card
    P->>S: Calls paymentLink
    S-->>P: Returns hosted link
    P->>C: Redirects to link
    C->>G: Pays by card
    G->>S: Payment succeeds
    S->>S: Issues gift card
    S-->>P: Sends TRANSACTION_UPDATED
    G->>C: Shows success page

Points to remember

• The promo_id you send is the promotion-id from getPromotionsList. It is not the brand-id.
• Returning to your site or seeing a success page is not proof that the card was issued. Confirm through the webhook or by reading the transaction.
• A repeat visit to an already paid order is rejected with Link already used, but a narrow timing overlap between the browser return and the provider’s notification is still being hardened. Avoid refreshing the success page. Gift card API requests have no server-side idempotency.
• An unknown user_id is created automatically with blank details, so validate the user yourself before you create a link.
• Card issuance is confirmed by TRANSACTION_UPDATED. Keep a record of the transaction identifier.

Testing

Staging is sandboxed end to end. Use the published test cards and amounts in Testing on staging rather than real cards.

When to use the prepaid model instead

If you take payment on your own system, you use the prepaid model. See Prepaid balance management.