Sandbox Environment

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.

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

Open the sandbox

Go straight to sandbox.macropay.ai, or pick Go to sandbox from the organization switcher inside the dashboard.

Create an account and organization

Sandbox identities are separate from production. Create a fresh user and organization exactly as in the Quick Start — none of your live credentials carry over.

Issue a sandbox access token

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, Adyen, and Checkout.com. 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 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:

const macropay = new Macropay({
  server: 'sandbox',
  accessToken: process.env['MACROPAY_ACCESS_TOKEN'] ?? '',
})

s = Macropay(
    server="sandbox",
    access_token="<YOUR_BEARER_TOKEN_HERE>",
)

  s := macropaygo.New(
  	macropaygo.WithServer("sandbox"),
  	macropaygo.WithSecurity(os.Getenv("MACROPAY_ACCESS_TOKEN")),
  )

$sdk = Macropay\Macropay::builder()
    ->setServer('sandbox')
    ->setSecurity(
        '<YOUR_BEARER_TOKEN_HERE>'
    )
    ->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.

Bootup

Features

Integrate

Merchant of Record (MoR)

Sandbox Environment

What the sandbox is

Spin up a sandbox

Test a checkout

Point the API and SDKs at the sandbox

What’s different from production

​What the sandbox is

​Spin up a sandbox

​Test a checkout

​Point the API and SDKs at the sandbox

​What’s different from production

What the sandbox is

Spin up a sandbox

Test a checkout

Point the API and SDKs at the sandbox

What’s different from production