Balances guide

What this resource is for

Balances are used by publishers that fund gift cards from a prepaid balance held with Spendstream, often called the float.

When to use it

• Check the balance before you submit a gift card order.
• Trigger low-balance notifications for your finance team.
• Support reporting, reconciliation and funding forecasts.

Important implementation notes

• Only prepaid (float) publishers need this. If customers pay on the Spendstream hosted page, you do not draw from a balance.
• checkPBalance returns HTTP 400 with You are not allowed to use this api when your publisher has no float balance record. This is not a permissions problem. Ask Spendstream to create your balance record (a zero balance is enough) and the call will work.
• Calling checkPBalance can trigger a low-balance email to your billing contact when the balance is below your threshold, at most once an hour.
• A balance is a point-in-time value. Another order may use it between your check and your submission, so handle an insufficient balance response gracefully.
• Staging does not use a real float.

 
curl "https://staging-api.spendstream.io/v2/checkPBalance" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "User-Agent: YourApp/1.0"

Common mistakes

• Checking the balance once at start-up and never again.
• Calling this endpoint for a hosted payment publisher.
• Ignoring the body response value.

Related resources

• Gift Cards
• Transactions
• Payments

Endpoint reference

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