Test Your Integration in the Diameter Sandbox

The Diameter sandbox lets you simulate inbound wires, test end-to-end payment flows, and verify webhook handlers without real money.

The Diameter sandbox is a fully isolated test environment that mirrors the production API surface without moving real funds. Every API call hits api.sandbox.diameterpay.com and auth.sandbox.diameterpay.com instead of the production hostnames, and all data — end users, accounts, payments, counterparties — lives only in the sandbox. Use it to build and verify your integration before going live.

Sandbox credentials are separate from production credentials. Generate your sandbox client_id and client_secret from the Sandbox section of the Diameter dashboard.

---

​

Simulate an inbound wire

The sandbox exposes a /v1/simulation/payments endpoint that lets you credit a virtual account with test funds as if an inbound wire had arrived from an external bank. This triggers the same webhook events and balance updates that a real inbound wire would, letting you test your full receive-and-respond flow.

cURL

curl -X POST https://api.sandbox.diameterpay.com/v1/simulation/payments \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "x-idempotency-key: 550e8400-e29b-41d4-a716-446655440040" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "WIRE_INBOUND",
    "bank": "PORTAGE",
    "accountNumber": "YOUR_ACCOUNT_NUMBER",
    "amount": "500.00",
    "type": "DOMESTIC",
    "description": "Sandbox inbound wire for QA"
  }'

A successful simulation:

1. Credits YOUR_ACCOUNT_NUMBER with the specified amount in sandbox USD
2. Updates the account balance immediately (verifiable via GET /v1/accounts/{id}/balance)
3. Fires a PAYMENT_WIRE_INBOUND_POSTED webhook event to any matching subscriptions

The /v1/simulation/payments endpoint is only available in the sandbox. Calling it against the production base URL returns 403 Forbidden.

To skip the compliance screening step for internal transfers that get stuck in SCREENING_REQUESTED, prefix the description field with AUTO_APPROVE — for example, "description": "AUTO_APPROVE liquidity test". This sandbox shortcut lets you test the full happy path without waiting for manual review.

---

​

End-to-end test scenario checklist

Run through this checklist in order to validate every part of your integration — from user onboarding to final payment confirmation.

---

​

Testing webhooks locally

To receive sandbox webhook deliveries on your development machine, expose your local server to the internet using a tunneling tool:

ngrok

# Install ngrok, then run:
ngrok http 3000
# Use the generated https://xxxx.ngrok.io URL as your webhook subscription URL

When using ngrok, make sure to use the https:// URL (not http://) — Diameter rejects non-HTTPS webhook endpoints. Update your subscription URL every time you restart ngrok, since free-tier URLs change on each session.