API quickstart

This page takes you from staging credentials to your first working API calls. It follows the sequence that every integration uses, whichever products you offer.

The sequence

 
flowchart TD
    A[Choose model and products] --> B[Receive staging credentials]
    B --> C[Exchange credentials for a bearer token]
    C --> D[Create or synchronise users]
    D --> E[Retrieve brands, offers and categories]
    E --> F[Build the gift card or affiliate journey]
    F --> G[Configure webhooks]
    G --> H[Complete staging testing]
    H --> I[Request production keys]

Before you start

• Choose your integration model and the products you want to offer.
• Ask your account manager for staging credentials: an API key and a secret.
• Keep the secret on your server. Never place it in browser or mobile code.

The staging base URL is https://staging-api.spendstream.io/v2.

Step 1: Get a bearer token

Sign your API key and a UTC timestamp with your secret, then post the result to getToken. The full method, with examples in three languages, is on the Authentication page.

The token is valid for 10 hours and identifies your organisation, not an individual user. Cache it and reuse it.

Step 2: Register a user

 
curl -X POST https://staging-api.spendstream.io/v2/addNewUser \
  -H 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{"UID":"customer-12345","name":"Jane Doe","email":"jane.doe@example.com"}'

Only UID is required. It is your permanent identifier for the customer.

⚠️ Warning: A duplicate UID returns HTTP 200 with "response": 400 inside the body and no token. Check the body, and use getUsersList?UID= to fetch an existing user.

Step 3: Read the catalogue

 
curl https://staging-api.spendstream.io/v2/getBrands \
  -H 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  -H 'User-Agent: YourApp/1.0'

Use getCategories to organise brands and getPromotionsList for current promotions. Do not hard-code brand availability, because it changes.

Step 4: Build your journey

• Gift cards: create a payment link with paymentLink, using the promotion-id from getPromotionsList as promo_id. Do not use the brand-id. Follow the Testing payments on staging guide.
• Affiliates: read offers with getCashback and present tracked links to your users.

Step 5: Configure webhooks

Send Spendstream the URL where you want to receive events. Registration is manual. Two events are sent, TRANSACTION_UPDATED and USER_UPDATED.

Step 6: Test on staging

Complete your testing against staging, then follow the Go-live checklist.

Related pages

• Environments
• Authentication
• Go-live checklist
• Full API integration