Sandbox
A sandbox is a separate deployment of PimaBill that runs the same code as live but connects only to the payment providers' test accounts. Nothing you do there moves real money, and nothing there appears in live.
Switching between live and sandbox
The dashboard has a Sandbox switch at the foot of the sidebar, next to Documentation. Turn it on to see the same organisation's sandbox: its own customers, plans, payments and sk_test_ API keys. Turn it off to return to live. You sign in once, on live; the first switch opens your account and organisation in the sandbox, with the same role. Data never moves between the two.
Your code talks to each environment's API directly, with that environment's key:
| Live | Sandbox | |
|---|---|---|
| API base URL | https://api.pimabill.com/api | https://sandbox.pimabill.com/api |
| Dashboard | https://app.pimabill.com | The same, with the Sandbox switch on |
| Provider webhooks | https://api.pimabill.com/webhooks/{provider} | https://sandbox.pimabill.com/webhooks/{provider} |
| Key | sk_live_... | sk_test_... |
These are the hosted cloud's addresses; a self-hosted deployment has its own.
Everything you create has a different ID in each environment, because they are separate databases. Your own references don't change: plan and add-on codes and customer externalIds are whatever you set, so use the same ones in both and look records up by them. Store PimaBill IDs per environment, if at all.
Your webhook URL and signing secret are also per environment. Point the sandbox at your staging app and live at your production app (see Webhooks).
Managed payments in the sandbox
If your organisation is approved for managed payments on live, it's approved in the sandbox too. The first time you open managed payments there (or the Providers page, or Charge a customer), the sandbox account is set up from your live one, with the same business, contact and payout details, and is ready at once: no second application and no review. It takes test payments through the providers' test accounts.
If you apply in the sandbox before you're approved on live, the sandbox account is approved at the same moment as the live one.
How to tell them apart
| Live | Sandbox | |
|---|---|---|
| API keys | sk_live_... | sk_test_... |
| Dashboard | No banner | A "Sandbox: test money only" banner on every page |
| Emails | Sent to customers | Subjects start with [Sandbox], and they go only to people with a login or an invitation to an organisation; emails to test customers are logged, not sent |
GET /health | "environment": "live" | "environment": "sandbox" |
| Cloud plan | Free or Growth, with their limits | None: no plan limits and nothing to pay |
Keys work only where they were issued. A sk_live_ key sent to the sandbox, or a sk_test_ key sent to live, is refused with a message saying which environment it belongs to.
Getting started
- Sign in to the dashboard and turn on Sandbox.
- Copy your
sk_test_key from Settings → API keys and point your client at the sandbox API. - Connect payment providers with their test credentials: for example a Flutterwave test secret key (
FLWSECK_TEST-...), PayPal sandbox credentials, or Yo! Payments sandbox details. - Take payments using each provider's published test cards and numbers, and check that your webhooks receive the events.
When you are ready, repeat the setup on live with live credentials. Nothing is copied from the sandbox.
Running your own sandbox
A self-hosted deployment becomes a sandbox with one setting:
SANDBOX_MODE=true
Run it as its own deployment, with its own databases and secrets, next to your live one. To give the live dashboard its Sandbox switch, set on the live deployment:
SANDBOX_BACKEND_URL=https://sandbox.example.com # the sandbox API, as the dashboard container reaches it
SANDBOX_LINK_SECRET=... # 32+ characters, the same on both deployments
and the same SANDBOX_LINK_SECRET on the sandbox. Live then signs a two-minute link for the signed-in person, and the sandbox opens the same account with the same ids.
Managed payments can serve both: create a separate sandbox deployment there and route it only to provider connections marked as sandbox.
Sandbox data may be cleared from time to time.