Sandbox (test environment)
The sandbox is Dunning's test environment. It exists so you can integrate and validate your flow with no risk of touching a real debtor: in a dunning system, the worst mistake a test environment could make is to actually fire an email, SMS or WhatsApp — or file a credit-bureau negative record or a protest — against a real person. In the sandbox, that does not happen.
The sandbox mode behavior is already built into the code, but the sandbox as a public URL still depends on Kobana provisioning the infrastructure (isolated database, dedicated host). Until then, there is no sandbox URL or credentials to share. This page documents how the sandbox behaves; once the environment is live, its URL and test keys will be announced here. Need to test now? See the How to test while the sandbox is not up yet section at the end of this page, or contact support.
The master lock: nothing real reaches the debtor
When the application runs with APP_ENVIRONMENT=sandbox, a server-side master lock unconditionally blocks any external effect that would reach the debtor. This is defense in depth: the lock holds even if a sending provider is configured by mistake — it does not rely on the absence of credentials.
In practice, in the sandbox:
- Email, SMS and WhatsApp are simulated. The notification is recorded as sent (
status: sent), but no message goes out — no provider (SendGrid, Twilio, Meta...) is called. The simulated send is tagged with anexternalIdshaped likesandbox:<channel>andcost: 0. - Nothing is charged. No calls to a production payment gateway.
- Credit-bureau negatives and protests reach neither the bureau nor the notary. They run against simulated adapters.
In other words: you exercise the dunning rules end to end and observe the result, without a single real communication reaching anyone.
What actually works in the sandbox
The sandbox simulates only the effects that would reach the debtor. Everything else works normally, so you can really test your integration:
- The full API v1 responds for real — authentication, creating and reading charges, people, agreements, rules, and so on. The responses are real; only the external dispatch is simulated.
- Outbound webhooks keep firing. This is the key point for the integrator: your endpoint receives the events normally (for example
notification.sent), so you can test webhook receipt and processing end to end. Simulated-send events carry"sandbox": truein the payload so you can tell them apart in testing. - Reading integrations works. Querying the state of the account's integrations responds normally.
Visible banner
Every dashboard and debtor-portal screen, when served in sandbox, shows a fixed banner warning that this is a test environment and that no real charge or communication is sent. It is a visual reminder paired with the server-side master lock — you cannot confuse the test environment with production.
Summary: simulated vs. real
| In the sandbox | Behavior |
|---|---|
| Email / SMS / WhatsApp to the debtor | Simulated — marked as sent, nothing goes out |
| Charging via gateway | Simulated — no real charge |
| Credit-bureau negative / notary protest | Simulated — test adapters |
| API v1 (auth, charges, people, agreements, rules...) | Real — responds normally |
| Outbound webhooks | Real — fire for real (with sandbox: true) |
| Reading integrations | Real — works normally |
| "Test environment" banner | Always visible in dashboard and portal |
How to test while the sandbox is not up yet
Until the public sandbox exists, you can develop safely against production:
- Use an account with no sending channels configured — sends are already simulated (the sending channels throw an error when no provider is set, so nothing goes out).
- Prefer read-only keys wherever writing is not needed.
- Validate mutations with
X-Idempotency-Keybefore automating.
Once the sandbox is up, you will point your integration at the test URL (to be announced) and get the master lock by default, without having to carefully configure the account.