Skip to main content
The sandbox is a full rehearsal of the payment flow that never touches the blockchain. You create invoices, drive them through their lifecycle by hand and receive the same signed webhooks your production integration will receive — all before your domain is verified and while your account is still pending. Sandbox data is completely separate from live data. Sandbox invoices never credit a balance, never appear in your statistics, never earn a fee and are never seen by any payout. They are also disposable: sandbox invoices and webhook logs are deleted automatically after 90 days.

Getting a sandbox key

Generate one in the dashboard on the Sandbox tab of your merchant. It looks like this:
The prefix is what matters: any key starting with sk_sandbox_ is routed to the sandbox. Everything else stays the same — same host, same paths, same request and response shapes:
Switching an integration between environments is therefore a one-line change: swap the key.
Never use a sandbox key in production, and never use a live key against test code. A sandbox invoice is not payable — its address_to is deliberately not a valid address on any chain and starts with SANDBOX.

What works in the sandbox

Anything that moves or reports real money is refused outright rather than answered with misleading empty data.

Simulating a payment

A live invoice’s status is decided by the chain. In the sandbox you decide it:

Parameters

string
required
One of success, partially_paid, paid_over, expired, cancelled, failed, refunded.
number
Amount paid, in the invoice’s fiat_currency. Defaults to the full amount for success, half for partially_paid and 125% for paid_over.
boolean
default:"true"
Whether to deliver the webhook for this transition.
string
Override the webhook destination for this call only — handy for pointing at a local tunnel while you develop.
The response includes the delivery result, so a failing endpoint shows up immediately instead of disappearing into a retry queue.

Sandbox webhooks

Sandbox webhooks are byte-for-byte the same as live ones, with two additions that let you assert you are not in production:
  • the payload carries "sandbox": true
  • the request carries an X-Paw-Sandbox: true header
The X-Paw-Signature header is computed with your sandbox key, so a receiver that verifies against the live key will correctly reject a sandbox webhook. Verify exactly as you do in production, using whichever key the environment is configured with — see Webhooks. Deliveries are logged and readable through GET /api/v2/notifications with your sandbox key, and on the Sandbox tab in the dashboard.

Going live

  1. Verify your domain and finish onboarding.
  2. Generate a live API key in the dashboard.
  3. Swap sk_sandbox_… for the live key in your configuration.
No other change is required.