Environment overview
Sandbox Environment
Test your integration without affecting real data or processing actual payments
Live Environment
Production environment for real customers and actual payment processing
Sandbox environment
Sandbox runs the same billing engine and the same API as live, on separate data. Use it to build and test your integration without moving real money.Accessing sandbox
- Platform Dashboard: https://platform.sandbox.paygentic.io
- API Base URL:
https://api.sandbox.paygentic.io
Key features
- Same login credentials: Use the same email and password as your live environment account
- Isolated data: All data is completely separated from the live environment
- Unique IDs: All resource IDs (customers, subscriptions, products, etc.) are unique to sandbox
- Same API: Every endpoint in live is also in sandbox, served from the same codebase. See What differs from live for the exceptions
- Test API keys: API keys are prefixed with
sk_test_and only work in sandbox
While you use the same login credentials for both environments, all data, API keys, and resource IDs are completely separate between sandbox and live.
What differs from live
- No real money moves. Payment providers run in their test modes. Card payments and refunds complete without a transfer of funds.
- Sandbox-only test controls. The dashboard adds controls to advance payment onboarding and simulate payment events without a real provider account. The API adds test clocks and a data reset. None of these exist in live.
- Sandbox tax calculation has a quota. Each sandbox account can produce a limited number of tax documents. When the quota is used up, invoice creation fails with a
400error until support resets the quota. - Data never crosses over. Products, plans, customers, usage and webhooks you create in sandbox do not exist in live. See Data synchronization.
When to use sandbox
Use the sandbox environment to:- Test your integration during development
- Validate new features before deploying to production
- Experiment with pricing models and configurations
- Train team members on the platform
- Debug issues without affecting real customers
- Run automated integration tests
Simulating time
A test clock replaces the current time for the subscriptions attached to it. Use one to test renewals, resets and invoices without waiting, or to build months of usage and invoice history.- Create a clock with
POST /v0/testClocks.currentTimecan be in the past, so a subscription on the clock can start on a past date and bill its periods as the clock advances. - Create subscriptions with
testClockIdset to the clock’s ID. The clock’s time is “now” for those subscriptions: their start, their billing, and their allowances. - Send usage with
timestampset to the clock’s current time. - Advance the clock with
PATCH /v0/testClocks/{id}, with eitheradvanceBy(an ISO 8601 duration, such as"P1M") or a latercurrentTime. - Repeat steps 3 and 4 for each period you want to simulate.
Advance a test clock by one month
- A clock moves forward only, and at most 1 year per call. A step back, or a step of more than 1 year, returns
400 Bad Request. To move further, advance more than once. - Usage counts once the clock moves past it. Usage dated at the clock’s current time doesn’t count yet, so advance the clock before you read a balance or an invoice. Paygentic processes usage events in the background, so a balance can take a short time to include them.
- Usage dated before an allowance starts never counts. Send usage dated at the clock’s time, not earlier. See Usage dated in the past.
- Invoices follow in the background. After an advance, Paygentic closes the periods the clock has passed. An invoice can take a short time to appear.
Resetting sandbox data
POST /v0/merchants/{merchantId}/reset deletes sandbox data so you can start again. Use it to fix a mistake in a test setup, such as a paid invoice you can’t undo, instead of contacting support.
Delete every customer, keep the catalog
- Nothing is deleted by default: with
scope: "merchant",keepCatalogis required. Your account configuration is always kept. - The reset exists in sandbox only. Only an organization owner or admin can call it. An API key has the permissions of the user it belongs to.
- Send no usage events while a reset runs. An event that arrives during the reset can survive it.
204 No Contentmeans every delete is done or scheduled. Usage events finish deleting in the background, so wait a short time before you create new data.502 Bad Gatewaymeans the reset is incomplete. Call it again with the same body to finish it. Calling it again is always safe.
Live environment
The live environment is your production environment where real transactions occur.Accessing live
- Platform Dashboard: https://platform.paygentic.io
- API Base URL:
https://api.paygentic.io
Key features
- Production data: Real customers and actual payment processing
- Live API keys: API keys are prefixed with
sk_live_and only work in live - Real payments: All transactions process actual payments
API keys and environments
API keys are environment-specific and identified by their prefix:Key restrictions
- Sandbox keys (
sk_test_) can only be used withhttps://api.sandbox.paygentic.io - Live keys (
sk_live_) can only be used withhttps://api.paygentic.io - Using a key with the wrong environment will result in authentication errors
Sandbox API Request
Live API Request
Best practices
Development workflow
- Develop in sandbox: Build and test your integration in sandbox first
- Use environment variables: Store API keys and base URLs in environment variables
- Automated testing: Run integration tests against sandbox in your CI/CD pipeline
- Validate changes: Test all changes in sandbox before deploying to live
- Monitor both environments: Set up monitoring for both environments
Security considerations
- Never commit API keys to version control
- Use separate API keys for each environment
- Rotate keys regularly in both environments
- Restrict live API keys to production servers only
- Use sandbox keys for local development and testing
Switching between environments
To switch between environments:- Update API key: Use the appropriate
sk_test_orsk_live_key - Update base URL: Point to the correct API endpoint
- Verify environment: Check that you’re working with the intended environment before making changes
Data synchronization
When moving from sandbox to live:- You’ll need to recreate products, plans, and pricing configurations in live
- Customer data must be created fresh in live
- Usage events and billing history are separate in each environment
- API keys and webhooks must be configured separately
Troubleshooting
Wrong API key for environment
Error Response
sk_test_ for sandbox, sk_live_ for live) and the matching API base URL.