Sandbox Testing
Use sandbox to prove your integration before live payments. Keep sandbox and live credentials separate.
Environment note: Never reuse live API keys, webhook secrets, payout keys, or payout destinations in sandbox tests.
What to test first
- Create a customer.
- Create a fixed amount invoice.
- Render or share payment instructions.
- Receive the invoice webhook.
- Verify the webhook signature using raw body.
- Fetch the canonical invoice.
- Mark your test order as paid.
Required pre-live test sequence
Use this sequence before moving an integration to live mode.
| Step | Test | Expected result |
|---|
| 1 | Create a customer. | Customer ID and reusable addresses are returned where supported. |
| 2 | Create a fixed amount invoice. | Invoice is pending and has correct token, chain, and network. |
| 3 | Complete a test payment. | Invoice moves through observed/confirming states and reaches paid or overpaid. |
| 4 | Verify webhook signature. | Invalid signatures fail; valid events are accepted once. |
| 5 | Fetch canonical invoice after webhook. | Your backend fulfills only from PayChain invoice state. |
| 6 | Reconcile balances and transactions. | Invoice, transaction, and balance views agree with the expected test result. |
| 7 | Test the highest-risk outbound flow you plan to use. | Withdrawal, payout route, dynamic recipient, or contract action behaves as expected. |
Launch rule: Do not launch a flow you have not tested. If your v1 launch uses only fixed invoices, document payout routes, dynamic recipients, and programmatic withdrawals as future work instead of partially enabling them.
Payment flow tests
Test the flows you plan to use:
- Fixed amount invoices.
- Auto-detected payments.
- Payout route invoices.
- Dynamic payout recipients.
- Programmatic withdrawals.
If a flow is not part of your production launch, document it as future work instead of testing it halfway.
Webhook tests
Confirm:
- Your endpoint receives PayChain test events.
- Signature verification passes with the raw body.
- Invalid signatures fail closed.
- Duplicate events do not double-credit a user.
- Failed deliveries can be retried or replayed.
Payout tests
For payout automation:
- Use a payout API key only on the backend.
- Validate destination addresses before creating payouts.
- Quote before creating a withdrawal.
- Use idempotency keys.
- Confirm webhook updates for final status.
Payout route and dynamic recipient tests
If your launch uses automated payout routing:
- Create an approved payout route in the dashboard.
- Create an invoice with
payoutRouteId.
- Fully pay the invoice.
- Confirm PayChain creates one withdrawal leg per recipient.
- Confirm every leg counts against payout API withdrawal quota.
- Confirm failed legs are visible to operators.
If your launch uses dynamic payout recipients:
- Create the invoice from a trusted backend with a payout API key.
- Validate the receiver before calling PayChain.
- Confirm recipient shares total 100%.
- Confirm PayChain rejects invalid destination, network, or policy combinations.
- Fully pay the invoice and reconcile the generated withdrawal.
Gas credit tests
Confirm your operators understand:
- Included gas credits.
- Prepaid gas credits.
- Gas top-up packs.
- Gas-blocked operations.
- The fact that inbound payment detection continues even when sponsored outbound actions pause.
Go-live readiness
Before going live:
- Switch to live API base URL and live keys.
- Register live webhook URL.
- Verify live webhook signature handling.
- Confirm plan, billing, gas credits, and payout quota.
- Confirm supported networks and tokens.
- Run one small live invoice test if approved by your rollout policy.