FAQ

Is the bearer token per user?

No. The token is scoped to your publisher and is valid for ten hours. Fetch one and reuse it for all your customers.

How often can I call getToken?

Five requests per minute. Today this limit is one bucket shared across the platform, so cache your token rather than fetching it repeatedly.

What happens if I call addNewUser twice with the same UID?

You receive HTTP 200 with a body response of 400 and the message “User already exists with UID”. No token is returned. Look the user up with getUsersList using the UID.

What does getUsersList return for an unknown UID?

HTTP 200 with total-users of 0 and an empty users-list.

Is promo_id the brand-id or the promotion-id?

The promotion-id from getPromotionsList. Sending a brand-id returns a 400 with “no promotion found connection”.

How do I send a white-label customer to the storefront?

Redirect the browser to https://YOUR_SUBDOMAIN.spendstream.co/login/YOUR_TOKEN, where the token is a path segment. You can add ?redirecturl=. A bad token silently redirects to the homepage, so fetch the token for each visit. See the white-label guide.

Which test cards can I use on staging?

Visa 4900490000000501 and Mastercard 5591390000000504, with any future expiry and CVV 123. Amex is unsupported. An amount of 700.00 always declines and 600.10 returns a bank error.

Does staging spend real money or my prepaid balance?

No. Staging is sandboxed end to end, so no real money or balance is spent.

Does Spendstream sign webhooks?

Yes, with two headers. Signature is the hexadecimal HMAC-SHA256 of your API key, the timestamp and your webhook URL, keyed with your secret. TimeStamp carries the timestamp. The signature does not cover the body, so it proves the origin of the call but not the integrity of the body.

Are webhooks retried?

No. There is no retry or backoff today, and there is no event identifier. Deduplicate on the transaction or user identifier plus status, respond quickly with a 2xx status, and reconcile with getTransactionsList.

How do I register a webhook?

Registration is manual. Give Spendstream your URL.

How do I get production keys?

Spendstream issues them after a review of your staging integration. Complete and verify your staging work first, then ask your account manager.

What are the base URLs?

Staging is https://staging-api.spendstream.io/v2 and production is https://api.spendstream.io/v2.

Why do I get a 403 with “error code: 1010”?

Some HTTP clients send a default User-Agent, such as Python-urllib, that is blocked at the CDN. Set an explicit User-Agent header.

What is the whitelabel parameter?

It is internal. Do not send it in your requests.

Can a page refresh issue a gift card twice?

Spendstream now rejects a repeat visit to the success page for an order that is already paid, so a plain refresh should not issue a second card. A narrow timing overlap between the customer’s browser returning and the payment provider’s own notification is still being hardened, so do not rely on this alone: avoid refreshing the page and dedupe on your side. Gift card API requests have no server-side idempotency at all. See Fraud and duplicate prevention.

Why do I get a 403 saying “IP address not allowed”?

Your account has an IP allow-list and the request came from an address that is not on it. Ask Spendstream to add the address your server calls from. Matching is exact, with single IPv4 or IPv6 addresses and no ranges. If no list is set, this error cannot occur. See the authentication guide.