Integration guide

Manage wallet balance

Everything is prepaid. One balance per environment, in one currency, with a transaction for every movement.

Topping up

Top-ups are done in the partner portal, not through the API. Your sandbox balance is play money that we keep loaded, so sandbox testing never stops for funding reasons.

Monitoring

bash

curl -s https://app.journeystack.co/api/public/v1/wallet -H "Authorization: Bearer $JS_KEY"

Check the balance on a schedule — hourly is enough — rather than before every order.
Subscribe to wallet.low_balance. We send it after an order when your remaining balance is under three times that order's total.
Set your own floor too: a balance that covers a normal day of sales is a sensible alert threshold.

Transactions

json

{
  "id": "7d1b0a46-1f66-4b1a-97cd-8a2ce0ff1c2d",
  "type": "debit",
  "amount": -17.15,
  "balance_after": 9825.4,
  "currency": "USD",
  "description": "Order b1f0a3c9-70d2-4b55-9a3f-4f2e1c8d9a10",
  "created_at": "2026-01-14T09:31:01.990Z"
}

type is credit (a top-up), debit (an order), refund (a failed order) or adjustment (a manual correction by Journey Stack).
amount is signed; debits are negative. balance_after lets you rebuild the running balance without summing.
Order debits and refunds carry the order ID in description, which is how you reconcile against your own ledger.

Currency

Your account has one billing currency (USD, EUR, GBP, SGD or INR). Every price, order and transaction is expressed in it, converted from our base rates at the moment of the call. Ask support if you need to change currency — existing transactions keep the currency they were made in.

An empty balance blocks selling

`insufficient_funds` is returned before anything is issued, so a failed order costs nothing — but it is still a lost sale. Keep a buffer, and alert on the low balance webhook.