Sandbox Mode

Sandbox mode lets you test the full Plaidly integration — session creation, on-chain detection, webhook delivery — without spending real funds.

How it works

When you create a session with "network": "testnet", Plaidly monitors the corresponding testnet chain. Use testnet tokens to trigger payment events.

Webhooks are delivered to your merchant webhook_url exactly the same as in production.

Testnet faucets

Fetch the current chain:network -> faucet URL map rather than hardcoding it — faucet operators change URLs without notice:

curl https://api.plaidly.io/v1/sandbox/faucets

Sandbox API keys

A merchant's key type is fixed at registration via the sandbox boolean, not chosen per-request. Test keys (plaidly_sk_test_..., from "sandbox": true) always use testnet networks regardless of the network field on a session. Live keys (plaidly_sk_live_...) require "network": "mainnet" and are not issued to unauthenticated callers.

Simulating payments

You can also trigger payment events without sending a real transaction using the sandbox simulation endpoint. It takes no request body:

curl -X POST https://api.plaidly.io/v1/payment_sessions/<SESSION_ID>/simulate \
  -H "X-API-Key: your_sandbox_api_key"

X-API-Key is required for a merchant-owned sandbox session (the request must come from the owning principal); it's optional for a public demo session created via POST /v1/payment_sessions/demo. This fires the webhook immediately, useful for CI/CD testing — see Simulate a payment for the full recipe.

Limitations

• Sandbox sessions do not appear in production analytics
• Rate limits are the same as production
• Webhook retries work identically