Each buyer organization has one wallet in your application: a prepaid balance in credits, with a history that is only ever added to. End users fill it by paying on your Stripe account; overage on capabilities that have an overage price is taken from it, as described in When the allowance runs out. A wallet is created with a balance of 0 the first time it is needed, for example when the organization's first subscription becomes active.
Top up
End users top up on the billing page of the customer portal (Add Credits), or your own page calls POST /public/v1/wallet/topup/checkout with:
| Field | Meaning |
|---|---|
amount_usd | The amount to pay, in US dollars; at least 1 |
success_url, cancel_url | Where Stripe Checkout returns to |
The answer has checkout_url, a Stripe Checkout page for a one-time payment on your Stripe account, and credits_expected: the amount times the wallet's currency_rate, the number of credits per US dollar. The credits are added when Stripe's checkout.session.completed event arrives, and Stripe saves the card for later automatic top-ups. A top-up needs an owner or admin of the organization with a verified email address, and a payment connection; without one the answer is 503 PAYMENT_PROVIDER_NOT_CONFIGURED.
Top up automatically
An organization can have its wallet topped up whenever overage leaves the balance below a threshold. End users set it up on the same billing page, or with GET and PATCH /public/v1/wallet/auto-recharge:
| Field | Meaning |
|---|---|
auto_recharge_enabled | Turns automatic top-ups on or off. Turning them on needs a saved card, so the organization has to top up through checkout once first |
credit_threshold | The balance, in credits, below which a top-up starts |
auto_top_up_amount | The amount charged each time, in US dollars, from 5 to 5,000. When that would not bring the balance back to the threshold, the charge is larger |
has_payment_method | Whether a card is saved (read only) |
How an automatic top-up runs:
- It starts after the overage that crossed the threshold has been taken, never in the middle of a ruling, and charges the saved card on your Stripe account without the end user present.
- The credits are added only when Stripe's
payment_intent.succeededevent arrives, so register thepayment_intentevents listed in The events to send. - One automatic top-up runs at a time per organization, and within a day (UTC) they add up to at most three times
auto_top_up_amount. - A declined card is tried again after 1 hour, 6 hours and 24 hours. If all three fail, or the bank asks the card holder to confirm the payment, automatic top-ups are turned off for that organization. Turning them on again resumes them.
ShipRev does not tell end users when an automatic top-up is charged, retried or turned off, and the settings on the customer portal show only the threshold and the amount. If you offer automatic top-ups, tell your end users how they are charged, including that a charge can be larger than the amount they set, and the daily limit.
Balance and history
| Who | Where |
|---|---|
| End users | The billing page of the customer portal, or GET /public/v1/wallet for the balance and GET /public/v1/wallet/transactions for the history, newest first, 20 a page by default and at most 100 |
| You | GET /mgt/v1/projects/{projectId}/wallets/{orgId} for one buyer organization |
Each history entry has its type, such as TOPUP or DEBIT, the signed amount in credits, the balance_after it, the reference it came from, such as the checkout or the usage event, and occurred_at. Entries are never changed or removed; a correction is a new entry.