Skip to main content

​
Using test mode

Test mode is driven by your tri_test_... API key plus a test webhook. No real funds move and no chain is involved — you trigger payments to completion and Tribridge fires your test webhook exactly like a live payment.
1

Register a test webhook

Create a webhook endpoint with is_test: true pointing at your server. For localhost, expose it with a tunnel (e.g. ngrok) so Tribridge can reach it.
2

Create a test payment

Call POST /payments with your tri_test_... key and open the returned checkout_url.
3

Simulate the payment

On the checkout page, click Simulate Payment (test mode only). The payment drives straight to completed and your test endpoint receives the full event sequence with is_test: true.
4

Verify your handler

Confirm your signature check passes, your order updates, and mismatches (try an underpaid simulation path if available) behave correctly. Only then switch to live keys.
Test mode ≠ testnet. Merchant-facing test mode (test keys + test webhooks) is fully simulated on production. Public devnet/testnet networks are used internally by the Tribridge team and are not part of the merchant API. When you’re ready for real money, switch to your tri_live_... key with live webhooks on mainnet.

​
Sandbox best practices

  • Always test your webhook signature verification in test mode before going live.
  • Use separate environment variables for test and live keys so they can’t be mixed up.
  • Verify your system handles payment.expired correctly (e.g. simulate an unpaid payment passing its window).
  • Make handlers idempotent — key off payment_id + event — since retries can deliver twice.
  • Test underpaid/overpaid handling, not just the happy path (see Refunds).

​
Local testing bridge — coming soon

A local testing companion (webhook forwarding + payment simulation from your terminal, no tunnels required) is on the roadmap. Today, the tunnel + Simulate Payment flow above covers the same ground. Availability will be announced at launch.