Payments guide

What this resource is for

Payments are for Full API publishers who use the Spendstream hosted payment gateway. The paymentLink endpoint creates a secure hosted payment link for a gift card purchase. The customer pays on the Spendstream checkout, which is provided by our payment provider, before the card is issued.

When to use it

• Your customers pay for gift cards directly, and you do not hold a prepaid float.
• You want Spendstream to handle card entry and payment security.

The hosted payment flow

 
flowchart TD
    A[Customer chooses a card] --> B[Your server calls paymentLink]
    B --> C[Spendstream returns a hosted URL]
    C --> D[Redirect customer to the URL]
    D --> E[Customer pays]
    E --> F{Payment result}
    F -->|Success| G[Spendstream issues card via supplier]
    G --> H[TRANSACTION_UPDATED webhook]
    F -->|Declined| I[Show a retry option]

Important implementation notes

• promo_id is the promotion-id from getPromotionsList, not the brand-id.
• Do not assume payment succeeded because the customer came back. Wait for TRANSACTION_UPDATED or confirm through the transactions resource.
• There is no server-side idempotency. Create one order record on your side and reuse the same link for retries where you can. Never create several links for one purchase.
• Avoid refreshing the payment success page. A repeat visit to an already paid order is rejected with Link already used, but a narrow timing overlap is still being hardened, so do not rely on it. Tell customers not to refresh, and make your own return page safe to reload.
• Validate user_id yourself. An unknown user_id is created automatically with blank details, so register real users first with addNewUser.
• Float-model publishers should use giftCardRequestApi instead.

Testing on staging

Staging is sandboxed. Use the published test cards (Visa 4900490000000501 or Mastercard 5591390000000504, any future expiry, CVV 123). American Express is not supported. An amount of 700.00 always declines, and 600.10 returns a bank error. See the testing guide for full detail.

 
curl -X POST "https://staging-api.spendstream.io/v2/paymentLink" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -H "User-Agent: YourApp/1.0" \
  -d '{"promo_id": "PROMOTION_ID", "user_id": "YOUR_CUSTOMER_ID", "amount": "50.00", "currency": "GBP"}'

The exact request fields are listed in the API reference.

Common mistakes

• Using a brand-id as promo_id.
• Marking an order paid when the customer lands on your return page.
• Creating a new link on every retry.
• Refreshing the success page while testing.

Related resources

• Gift Cards
• Promotions
• Users
• Transactions

Endpoint reference

The v2 endpoint for this resource is paymentLink. Exact parameters, schemas and responses are in the API reference.