# Sandbox Testing

Use sandbox to prove your integration before live payments. Keep sandbox and live credentials separate.

{% hint style="warning" %}
**Environment note:** Never reuse live API keys, webhook secrets, payout keys, or payout destinations in sandbox tests.
{% endhint %}

### What to test first

1. Create a customer.
2. Create a fixed amount invoice.
3. Render or share payment instructions.
4. Receive the invoice webhook.
5. Verify the webhook signature using raw body.
6. Fetch the canonical invoice.
7. 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. |

{% hint style="success" %}
**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.
{% endhint %}

### 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:

1. Create an approved payout route in the dashboard.
2. Create an invoice with `payoutRouteId`.
3. Fully pay the invoice.
4. Confirm PayChain creates one withdrawal leg per recipient.
5. Confirm every leg counts against payout API withdrawal quota.
6. Confirm failed legs are visible to operators.

If your launch uses dynamic payout recipients:

1. Create the invoice from a trusted backend with a payout API key.
2. Validate the receiver before calling PayChain.
3. Confirm recipient shares total 100%.
4. Confirm PayChain rejects invalid destination, network, or policy combinations.
5. 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.paychainhq.io/paychainhq-documentation-page/dashboard-guides/sandbox-testing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.