Appearance
Testmode
Testmode is a sandbox realm that lives inside your normal service - not a separate environment. Customers (and everything that descends from them: orders, payments, subscriptions, balances) can be tagged as test data, letting you exercise the full integration - checkout, subscriptions, dunning, webhooks - without generating real invoices, sending real emails, or moving real money.
Unlike a separate staging deployment, testmode data lives alongside your live data under the same service and credentials family. It's tagged, not physically separated.
Testmode orders activate testmode checkouts on partners (e.g. Mollie, Stripe and PayPal). Testmode orders will never capture real money.
Service x Testmode
After setting up TiruPay and configuring your service, use the Testmode to integrate TiruPay into your service. This way, you can soundly test your integration and get to know the TiruPay logic. Once you are ready, switch to the production mode. And the best thing: changing to production only requires you to change the API key (and any webhook secrets). Any hard coded ID stays the same.
Test Mode Limitations
When using the Test API Key we return testmode objects for the 'Relations' realm. Relations are e.g. Orders, Customers and Withdrawals. Production objects are never returned in the 'Relations' realm. Objects from different realms, e.g. those who do not have a testmode flag, are returned equivalent in both test and production mode. This is expected and wanted behavior. The testmode is established to enable services to test their current configuration. Performing operations outside of the 'Relations' realm with the test API key should be limited to GET requests! We do not lock the test service user from manipulating objects outside the 'Relations' realm but note that any of those changes can and will affect real users. In short: the test service user can manipulate your service configuration (articles, balances, settings, etc.) which can affect production customers.
Getting into testmode
A service can have one Test Service User - a second Service account for the same service. Every customer it creates, and everything that customer goes on to do, is automatically tagged as testmode.
An Admin can also create a customer directly in testmode, for example to test the admin frontend. A Test Service User has no choice in the matter - its customers are always testmode.
Once a record is created, its realm never changes.
Creating a Test Service User
A test service user can be created using the admin dashboard. Head to More Settings > Users.
What's different in testmode
- No real invoices. Dunning still runs its internal ladder on testmode orders so you can test the full flow, but nothing is ever sent to your invoicing provider.
- No real emails. Mail destined for a testmode customer is redirected to a configurable test address instead of the customer's real inbox.
- No real webhook deliveries to live endpoints. Testmode events are only delivered to webhook registrations explicitly marked as test - a live registration never receives testmode events, and a Test Service User can only register test ones. See Webhooks.
- No real money. Payments for testmode orders run through the payment provider's sandbox credentials. See Payments.
- Separate order numbers. Testmode orders get their own clearly-marked number sequence, distinct from your service's real invoice numbers.
The testmode field
| Field | Type | Description |
|---|---|---|
testmode | boolean | True if this record belongs to the test realm. Set once at creation; never changes afterward. |
This field appears on customers, orders, payments, subscriptions, service balances, credit balances, mandates, withdrawal requests, and users.
Good to know
Realm Is Inherited Automatically
You never set testmode yourself on an order, payment, or subscription - it always matches its customer.
JWT Login, OIDC and user creation
Both login flows support on-the-fly user creation but there are limitations. For users to have access to customers, they need to be marked as testmode. In the OIDC flow we cannot determine if your requests comes from the test sandbox. Therefore on-the-fly created users in the OIDC flow will not be marked with the testmode param! Instead create them first using our API. In the JWT flow, send the test api key in the Authorization header, the on-the-fly user creation then takes the correct testmode.
A user account is also tagged testmode and can only be linked to a customer in the same realm - linking across realms is rejected.
Relationships
- Services - the Test Service User is provisioned per service.
- User Roles & Permissions - a Test Service User is a Service account and authenticates the same way.
- Customers - realm is decided at customer creation and inherited by everything the customer does.
- Webhooks - test vs. live webhook registrations.
- Payments - sandbox behavior for testmode payments.