Skip to main content
Paygentic provides two separate environments to support your development workflow: Sandbox and Live. Use them to test your integration thoroughly before going to production.

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

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 400 error 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
Test data only: The sandbox environment is exclusively for testing purposes. Never add real user data, personal information, or production customer data to sandbox. Always use synthetic test data only.

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.
  1. Create a clock with POST /v0/testClocks. currentTime can be in the past, so a subscription on the clock can start on a past date and bill its periods as the clock advances.
  2. Create subscriptions with testClockId set to the clock’s ID. The clock’s time is “now” for those subscriptions: their start, their billing, and their allowances.
  3. Send usage with timestamp set to the clock’s current time.
  4. Advance the clock with PATCH /v0/testClocks/{id}, with either advanceBy (an ISO 8601 duration, such as "P1M") or a later currentTime.
  5. Repeat steps 3 and 4 for each period you want to simulate.
Advance a test clock by one month
Rules to know:
  • 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", keepCatalog is 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 Content means 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 Gateway means 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

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 with https://api.sandbox.paygentic.io
  • Live keys (sk_live_) can only be used with https://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

  1. Develop in sandbox: Build and test your integration in sandbox first
  2. Use environment variables: Store API keys and base URLs in environment variables
  3. Automated testing: Run integration tests against sandbox in your CI/CD pipeline
  4. Validate changes: Test all changes in sandbox before deploying to live
  5. 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:
  1. Update API key: Use the appropriate sk_test_ or sk_live_ key
  2. Update base URL: Point to the correct API endpoint
  3. Verify environment: Check that you’re working with the intended environment before making changes
Add environment indicators to your application’s admin panel or logs to clearly show which environment you’re working with.

Data synchronization

Data is not synchronized between sandbox and live environments. Each environment maintains its own independent database.
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
Important: Never copy real customer data or personal information from live to sandbox. Sandbox should only contain synthetic test data. Similarly, never use production customer data for testing purposes.

Troubleshooting

Wrong API key for environment

Error Response
Solution: Verify you’re using the correct API key prefix (sk_test_ for sandbox, sk_live_ for live) and the matching API base URL.

Data not found in new environment

If you’re switching from sandbox to live and can’t find your data, remember that environments are completely isolated. You need to recreate your configuration in the new environment.

Testing payments in sandbox

Sandbox environment uses test payment credentials that simulate real payment flows without processing actual charges. Contact support@paygentic.io for test payment credentials.