Sandbox

Deterministic fixtures and test triggers.

The sandbox behaves like production at the API surface but settles against deterministic fixtures. Tests should never fail because a network was busy.

Seeded state#

New sandbox accounts start with:

Asset	Balance
USDC	25,000.00
USDT	10,000.00
ETH	5.000000
SOL	250.000000

Recipients you create in sandbox are pre-cleared by screening unless you explicitly mark them as failing.

Triggers#

Traditionally you would wait for a chain. In sandbox, you decide.

bash

# Move a payment intent to a terminal state
curl -s -X POST "$JUICEPAY_URL/v1/sandbox/payment_intents/pi_test_123/succeed" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

curl -s -X POST "$JUICEPAY_URL/v1/sandbox/payment_intents/pi_test_123/fail" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

Trigger	Effect
`succeed`	Full amount, settles in 2 seconds.
`underpay`	80% of the amount.
`overpay`	120% of the amount.
`fail`	Terminal failure with a chosen error code.
`expire`	Immediately expires the intent.
`unsupported_chain`	Simulates payment on a chain you did not accept.
`revert`	Succeeds, then reverts after 30 seconds.

Simulating slow chains#

bash

curl -s -X POST "$JUICEPAY_URL/v1/sandbox/clocks" \
  -H "Authorization: Bearer $JUICEPAY_KEY" \
  -d '{ "settlement_delay_seconds": 45 }'

Every settlement in the sandbox account is delayed by the configured amount, which is the only sane way to test loading states and timeout handling.

Forcing errors#

Return any documented error code on demand so you can exercise your error paths:

bash

curl -s -X POST "$JUICEPAY_URL/v1/sandbox/payouts" \
  -H "Authorization: Bearer $JUICEPAY_KEY" \
  -H "JuicePay-Sandbox-Error: insufficient_balance" \
  -d '{ "amount": "2000.00", "asset": "USDC", "recipient": "rcp_test_1" }'

Valid values are any code from the errors reference.

Emitting events#

bash

curl -s -X POST "$JUICEPAY_URL/v1/sandbox/webhook_events" \
  -H "Authorization: Bearer $JUICEPAY_KEY" \
  -d '{ "type": "payment_intent.reverted", "object_id": "pi_test_123" }'

The event is signed and delivered exactly as a real one would be, so signature verification and deduplication logic are genuinely exercised.

Test card of chain fixtures#

Chain	Simulated finality	Notes
`base`	2s	Default target for most tests.
`solana`	3s	Fast path.
`arbitrum`	4s	—
`ethereum`	30s	Slow path; good for timeout tests.
`tron`	5s	Low-decimal asset behaviour.

Test keys and data hygiene#

Sandbox keys and production keys are not interchangeable, and sandbox objects cannot be imported into production. Seed fixtures in code rather than in the dashboard so your test suite starts from a known state.

bash

curl -s -X POST "$JUICEPAY_URL/v1/sandbox/reset" \
  -H "Authorization: Bearer $JUICEPAY_KEY"

Reset clears all sandbox resources and restores the seeded balances. Run it in test setup.