Testing payments on staging

Who this guide is for: publishers integrating gift card purchases through the hosted payment gateway (POST /paymentLink). White-label publishers who only implement SSO do not need this page; SpendStream handles payments on your behalf. See the White-Label SSO Integration Guide.

1. Confirming you’re on staging

Card payments are processed by a hosted payment provider. On staging, the payment URL returned by POST /paymentLink contains a test_ site reference:

 
https://payments.example.com/process/payments/details?sitereference=test_yourreference&...

💡 Check for test_ before entering any card details. Production site references do not carry the prefix. This is the reliable way to confirm you are in the sandbox, and it is more reliable than the environment name or the base URL you called.

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

Does a staging purchase cost real money?

No. Both halves of a purchase are sandboxed on staging:

You can confirm the second from the response: the giftcard-url on a staging purchase points at a sandbox host.

 
{
  "giftcard-url": "https://sandbox.example.com/...",
  "giftcard-face-value": 10,
  "giftcard-cost-value": 10,
  "currency": "GBP",
  "giftcard-expiry-date": "2028-08-21 00:59:59",
  "response": 200
}

Sandbox vouchers are not redeemable; the codes are simulated. Test as many times as you need.

⚠️ This applies to staging only. In production, both the payment and the voucher are real, and giftcard-cost-value is deducted from your float balance the moment the card is issued.

2. Test cards

Use these to produce a successful transaction:

• Expiry date: any valid future date
• Security code (CVV):123

To produce a failed transaction:

The payment provider publishes a longer list of test cards covering 3-D Secure and Strong Customer Authentication scenarios (frictionless pass and fail, step-up challenges, enrolment failures). Ask your Spendstream contact for it.

⚠️ American Express is not supported, on staging or in production. Some card lists include American Express test cards; those will not work with SpendStream. Use Visa or Mastercard.

Apple Pay and Google Pay are enabled.

3. Amounts that trigger specific responses

The test bank reacts to certain amounts regardless of which card you use. This catches people out; a test that fails for no apparent reason is often just an unlucky amount.

If you’re testing the happy path, use an amount that isn’t in this table. If you’re testing your decline handling, 700.00 is the simplest way to force one without changing card details.

4. A complete test run

The sequence below is the full purchase flow, verified end to end against staging.

1. Get a bearer token. See the authentication guide. It is valid for 10 hours, so cache it.

2. Register the end-user. The user must exist under your publisher before you can generate a payment link:

 
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":"test-user-001","name":"Test User","email":"test@example.com"}'

3. Find a promotion. GET /getPromotionsList returns promotions with a promotion-id and the brand-id they belong to. Cross-reference GET /getBrands to check the brand is "active": "Active"; promotions on inactive brands will not sell.

4. Generate the payment link:

 
curl -X POST https://staging-api.spendstream.io/v2/paymentLink \
  -H 'Authorization: Bearer YOUR_BEARER_TOKEN' \
  -H 'Content-Type: application/json' \
  -H 'User-Agent: YourApp/1.0' \
  -d '{
    "promo_id": 19968,
    "user_id": "test-user-001",
    "consent": "1",
    "currency": "GBP",
    "amount": 10
  }'

 
{
  "payment_link": "https://payments.example.com/process/payments/details?sitereference=test_...",
  "response": 200,
  "order-id": "17872646666a877e9aee2bf"
}

5. Complete payment at payment_link using a test card from §2.

6. On success, SpendStream issues the gift card, updates the user’s balance, and dispatches a TRANSACTION_UPDATED webhook to your registered endpoint.

⚠️ promo_id is the promotion-id, not the brand-id. Passing a brand ID returns 401 {"message": "no promotion found connection"}. Take the value from the promotion-id field of GET /getPromotionsList; the brand is resolved server-side from the promotion.

⚠️ Avoid refreshing the payment success page. A repeat visit to an order that is already paid is now rejected with Link already used, so a plain refresh should not issue a second card. A narrow timing overlap between the browser return and the payment provider’s notification is still being hardened, so do not rely on this. If you refresh during testing, check for duplicate orders before continuing.

5. Before going to production

• [ ] Swap the staging base URL for https://api.spendstream.io/v2
• [ ] Swap staging API key and secret for production credentials issued by SpendStream
• [ ] Confirm the payment URL site reference no longer carries the test_ prefix
• [ ] Remove any hard-coded test card handling from your checkout code
• [ ] Verify your webhook endpoint is reachable from production and validates the Signature header
• [ ] Test your decline path; production declines are real, and users will hit them