Skip to main content
TRXN provides a sandbox mode that lets you test your integration in an isolated environment without affecting production data. Sandbox data is completely separate from live data, so you can create test customers, invoices, and subscriptions without any risk.

​
How sandboxes work

The sandbox feature isolates data through a Sandboxable concern applied to core models. When sandbox mode is active, all data operations are scoped to the current sandbox context:
  • Sandbox records are only visible when the matching sandbox is active
  • Production records (where sandbox_id is null) are only visible outside of sandbox mode
  • Each sandbox has its own isolated dataset — customers, invoices, subscriptions, and all other tenant-scoped resources
Sandbox isolation is enforced at the query level through scoped queries, not through a database-level default scope. This means you must use the .sandboxed scope when querying models to ensure proper isolation.

​
Using sandbox mode

​
Through the application

Account users can select a sandbox from their account settings. Once a sandbox is selected, all operations within the application are scoped to that sandbox. Switching back to production mode clears the sandbox context.

​
Through the API

API tokens can be associated with a specific sandbox. When an API request is made with a sandbox token, the sandbox context is automatically set based on the token’s configuration. This means:
  • Production API tokens access production data only
  • Sandbox API tokens access sandbox data only

​
Data isolation

All core domain models support sandbox isolation:
ModelSandbox support
CustomersYes
ProductsYes
PricesYes
InvoicesYes
Line itemsYes
SubscriptionsYes
Subscription phasesYes
Subscription phase itemsYes
WalletsYes
Crypto addressesYes
Crypto transactionsYes
Payment claimsYes
Transaction allocationsYes
Webhook endpointsYes
Sandbox data and production data are completely separate. A customer created in sandbox mode will not be visible in production mode, and vice versa.

​
Creating sandbox API tokens

To test your integration against the API in sandbox mode:
1

Create a sandbox

Navigate to your account settings and create a new sandbox environment.
2

Generate an API token

Create a new API token and associate it with the sandbox you just created.
3

Use the token in requests

Include the sandbox API token in your API requests. All data returned and created will be scoped to the sandbox.
curl -H "Authorization: Bearer your_sandbox_token" \
  https://api.gettrxn.com/api/v1/customers

​
Adding sandbox support to new models

If you are extending TRXN with custom models, you can add sandbox support by including the Sandboxable concern.

​
Step 1: Add the migration

class AddSandboxIdToYourModels < ActiveRecord::Migration[7.0]
  def change
    add_column :your_models, :sandbox_id, :uuid
    add_index :your_models, :sandbox_id
  end
end

​
Step 2: Include the concern

class YourModel < ApplicationRecord
  include Sandboxable

  # Use the sandboxed scope for queries
  def self.some_query
    sandboxed.where(...)
  end
end

​
Webhooks in sandbox mode

Webhook events fired from sandbox data include sandbox context. This means you can set up separate webhook endpoints for sandbox and production, or use a single endpoint that distinguishes between the two based on the payload.

Crypto payments overview

End-to-end payment flow from product definition to transaction allocation.

Webhooks

Receive real-time notifications for events in your TRXN account.