Testing & Sandbox

Test your Crypto Gateway integration without moving real funds using the test_sk_* API key.

---

Test vs Production Keys

The key prefix determines the environment — no toggle needed:

Key Prefix	Environment	Blockchain	Funds
test_sk_*	Sandbox	Testnets (Sepolia, BSC Testnet, etc.)	No real funds
live_sk_*	Production	Mainnets	Real transactions

Send the right key; the API handles everything else. Use identical code in both environments.

// Development
const rach = new RachFinance({ apiKey: process.env.RACH_TEST_KEY }); // test_sk_...

// Production
const rach = new RachFinance({ apiKey: process.env.RACH_LIVE_KEY }); // live_sk_...

The is_test_mode flag is locked onto a session the moment the request is authenticated. A session cannot switch mode mid-flow.

---

Sandbox Balance

The sandbox provides a virtual USD balance for simulating checkout sessions.

Get Sandbox Balance

GET /api/v1/api-keys/sandbox/balance

GET /api/v1/api-keys/sandbox/balance
Authorization: Bearer <jwt>

Reset Sandbox Balance

POST /api/v1/api-keys/sandbox/reset

Resets all sandbox balances to their default values.

POST /api/v1/api-keys/sandbox/reset
Authorization: Bearer <jwt>

---

Sandbox Behaviour per Endpoint

Endpoint	Sandbox Behaviour
POST /api/v1/checkout/create	Returns real session + payment_url, no monthly cap checked
GET /api/v1/checkout/verify/{id}	Returns simulated paid after a short delay
POST /api/v1/checkout/{uuid}/select-network	Returns testnet address + mock QR
GET /api/v1/checkout/{uuid}/verify-now	Returns paid after simulated confirmation delay
Webhooks	Fire with test_ prefixed tx_hash values

---

Test Card / Crypto Simulation

In sandbox mode, after your customer selects a network on the hosted payment page, the session will automatically transition to paid after a short simulation delay — no real crypto needs to be sent.

You can also trigger it manually:

# Force check payment status (simulates confirmation in sandbox)
curl https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/checkout/{uuid}/verify-now \
  -H 'X-API-Key: test_sk_...'

---

Test Webhook Delivery

# Send a test webhook to your configured URL
curl -X POST https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/settings/webhook/test \
  -H 'Authorization: Bearer <jwt>'

This fires a webhook.test event, allowing you to verify:

• Connectivity between Rach and your endpoint
• Your signature verification code
• Your event handler logic

---

Pre-Launch Checklist

Before going live with live_sk_*:

• [ ] Webhook URL is HTTPS and publicly reachable
• [ ] Signature verification implemented and tested
• [ ] payment.confirmed (not payment.detected) triggers order fulfillment
• [ ] Order fulfillment is idempotent (safe to call twice)
• [ ] Partial payment edge case handled (status: "partial")
• [ ] Session expiry handled gracefully
• [ ] amount validated against order total in webhook handler
• [ ] Error responses from your webhook return non-2xx so Rach retries
• [ ] API key stored securely (not committed to source control)