> ## Documentation Index
> Fetch the complete documentation index at: https://docs.macropay.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Sandbox Environment
> A full, isolated clone of Macropay where you can build, break, and rehearse your integration without touching real money or live data.
Ship with confidence: the sandbox is a complete copy of Macropay running on its own infrastructure, so you can wire up checkout, meters, the AI proxy, and webhooks end-to-end before a single real charge goes through.
You can open it anytime at [sandbox.macropay.ai](https://sandbox.macropay.ai/start).
## What the sandbox is
The sandbox is a dedicated server with the **same API surface as production** — every endpoint, field, and SDK method behaves identically. The difference is that nothing here moves real money, settles to a real payout, or files a real tax return. Spin up as many accounts and organizations as you need to model different scenarios.
Because Macropay is your **Merchant of Record**, every transaction touches sales tax/VAT calculation, dispute handling, and PCI-scoped card data. The sandbox lets you exercise all of that machinery — without us becoming the seller of record on a real customer's statement.
**Why a separate environment instead of a "test mode" flag?**
As your Merchant of Record we have to keep an exact ledger of every money movement to remit tax and manage disputes correctly. Mixing test traffic into that ledger is risky, so we keep the two worlds physically apart. The upside for you: unlimited throwaway orgs and a clean slate whenever you want one. Treat it as your personal Macropay dev server.
## Spin up a sandbox
Go straight to [sandbox.macropay.ai](https://sandbox.macropay.ai/start), or pick **Go to sandbox** from the organization switcher inside the dashboard.
Sandbox identities are separate from production. Create a fresh user and organization exactly as in the [Quick Start](/introduction) — none of your live credentials carry over.
Generate a new access token from the sandbox dashboard. Tokens are scoped to the environment that minted them: a production token will be rejected here, and vice versa.
## Test a checkout
The sandbox walks the entire customer funnel, hosted checkout included. Use your processor's standard test cards — Macropay accepts the canonical numbers from [Stripe](https://docs.stripe.com/testing#cards), [Adyen](https://docs.adyen.com/development-resources/testing/test-card-numbers/), and [Checkout.com](https://www.checkout.com/docs/developer-resources/testing/test-cards). Card details are tokenized in our PCI DSS Level 1 compliant vault, just like production.
For a quick happy-path purchase, drop in the universal success card with any future expiry and any CVC:
```
4242 4242 4242 4242
```
Want to rehearse the failure cases too? Decline and 3-D Secure test cards from any of the three processors above work here, so you can confirm your webhook handling for failed and pending payments before launch.
## Point the API and SDKs at the sandbox
Talking to the [API](/api-reference) takes one change: swap the base URL from `https://api.macropay.ai` to `https://sandbox-api.macropay.ai`, and authenticate with a token created in the sandbox.
The official SDKs expose a dedicated `server` selector so you never hardcode the host:
```ts TypeScript theme={null}
const macropay = new Macropay({
server: 'sandbox',
accessToken: process.env['MACROPAY_ACCESS_TOKEN'] ?? '',
})
```
```py Python theme={null}
s = Macropay(
server="sandbox",
access_token="",
)
```
```go Go theme={null}
s := macropaygo.New(
macropaygo.WithServer("sandbox"),
macropaygo.WithSecurity(os.Getenv("MACROPAY_ACCESS_TOKEN")),
)
```
```php PHP theme={null}
$sdk = Macropay\Macropay::builder()
->setServer('sandbox')
->setSecurity(
''
)
->build();
```
The full platform is available in the sandbox, so you can dry-run the parts that are hardest to verify in production: ingest usage with the meters and credits flow, route model traffic through the OpenAI-compatible AI proxy at `/ai/v1`, and post agent activity and outcome data to the Signals API (`POST /v1/signals`) to watch value receipts and agentic margin populate — all without billing a real card.
## What's different from production
These rules apply **only** to the sandbox and do not reflect production behavior:
| Behavior | Sandbox | Production |
| --------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ |
| Subscriptions | Auto-canceled **90 days** after creation | Run indefinitely until canceled |
| Money movement | Simulated — no real charges, payouts, or settlements | Live |
| Access tokens | Sandbox-only; not interchangeable with production | Production-only |
| `customer_email` validation | Format only — **MX/deliverability check skipped**, so `user@example.com` works | Strict: the domain must accept mail (`@example.com` is rejected — use a real domain) |
Everything else — endpoints, request/response shapes, webhook signatures, and SDK behavior — matches production one-to-one, so anything you build against the sandbox transfers cleanly when you flip to live.
**Synthetic test emails:** in production, `customer_email` is validated against the domain's mail (MX) records, so throwaway addresses like `user@example.com` return a `422`. Use a domain that actually accepts mail (e.g. a real inbox, or `+tag` aliases on one you own). The sandbox relaxes this so you can drive automated tests freely.
**`success_url`:** Macropay only interpolates the literal `{CHECKOUT_ID}` placeholder into your `success_url` — e.g. `https://acme.dev/thanks?checkout_id={CHECKOUT_ID}`. It does **not** append any query parameters of its own (no `customer_session_token`, no `checkout_id`) — whatever you want in the redirect, put it in the template yourself.