Machine View
Testing Payments Safely
Source: https://conto.finance/docs/guides/testing-payments
# Testing Payments Safely
> Validate your integration on testnet, simulate policy outcomes, and test edge cases without risking real funds
- Human URL: https://conto.finance/docs/guides/testing-payments
- Raw Markdown: https://conto.finance/docs/guides/testing-payments.md
- Terminal view: https://conto.finance/ai/docs/guides/testing-payments
Documentation group: Guides
# Testing Payments Safely
Before going to production, you need confidence that your agent integration handles every scenario safely. This guide covers the testing **environments** (agent sandbox and Tempo Testnet), counterparty and time-window scenarios, and the migration to production.
For policy semantics and the amount-threshold trio (APPROVED / REQUIRES_APPROVAL / DENIED), run the three-tier threshold test in [Testing Spending Policies](https://conto.finance/guides/policy-testing).
## Prerequisites
An agent with an SDK key ([Quickstart](https://conto.finance/quickstart/setup)), or an agent sandbox (below)
For testnet scenarios: a funded Tempo Testnet wallet linked to your agent
## Choose Your Environment
### Fastest Lane: Agent Sandbox
The quickest way to test the payment lifecycle is the agent sandbox: `POST /api/agents/sandbox` creates a test workspace, agent, wallet, and SDK keys in one call, with no email verification or human approval. Sandbox test payments exercise policy evaluation, spend tracking, receipts, and audit logs without an onchain transfer, so you don't need a signer or a funded wallet.
See the [Agent Sandbox Quickstart](https://conto.finance/quickstart/agent-sandbox) for the full flow, including claiming the sandbox later.
### Tempo Testnet
When you want real onchain transactions, use Tempo Testnet:
| | Tempo Testnet | Production (Tempo / Base / Solana) |
| ------------ | -------------------------------------- | ---------------------------------------- |
| **Token** | pathUSD (free) | USDC.e on Tempo or USDC on Base / Solana |
| **Gas fees** | None | Covered by Conto |
| **Onchain** | Yes, real blockchain transactions | Yes |
| **Policies** | Fully enforced | Fully enforced |
| **Best for** | Integration testing, policy validation | Live agent operations |
Tempo Testnet gives you real onchain transactions with real policy enforcement, using free test
tokens. Your core request code can stay the same when you switch to production, but production
credentials, custody, policies, approvals, webhooks, monitoring, and incident controls must be
configured separately. The [Quickstart](https://conto.finance/quickstart/setup) covers creating and funding a testnet
wallet; use the [Production Readiness Checklist](https://conto.finance/guides/production-readiness) before enabling live
funds.
## Test Plan
This guide walks through two scenarios beyond the amount thresholds:
| # | Scenario | Expected Result |
| --- | ------------------------------- | --------------- |
| 1 | Payment to blocked counterparty | DENIED |
| 2 | Payment outside time window | DENIED |
For amount-based outcomes: a `REQUIRES_APPROVAL` payment appears in **Pending Approvals** in the dashboard, where a human can approve or reject it; after approval, the agent can execute it (poll for the status change, or use [webhooks](https://conto.finance/guides/webhooks) to get notified). For handling `DENIED` and `REQUIRES_APPROVAL` statuses in code, see [Error Handling](https://conto.finance/sdk/error-handling#using-request-and-execute-for-better-control).
## Scenario 1: Blocked Counterparty
First create and assign the policy:
Go to **Policies** → **Create Policy**.
| Field | Value |
|-------|-------|
| Name | Test: Blocked Address |
| Policy Type | COUNTERPARTY |
| Field | Value |
|-------|-------|
| Rule Type | BLOCKED_COUNTERPARTIES |
| Value | `0xBLOCKED0000000000000000000000000000dead` |
| Action | DENY |
Add it in the **Permissions** tab.
Then send a $5 payment to the blocked address:
```bash
curl -X POST https://conto.finance/api/sdk/payments/request \
-H "Authorization: Bearer $CONTO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 5,
"recipientAddress": "0xBLOCKED0000000000000000000000000000dead",
"purpose": "Test: blocked recipient"
}'
```
**Verify:**
- Response `status` is `"DENIED"`
- `reasons` explains that the current payment controls do not allow the recipient
- Amount doesn't matter. The address itself is blocked
## Scenario 2: Time Window Restriction
To test time-based restrictions, temporarily add a time window policy:
| Field | Value |
|-------|-------|
| Name | Test: Business Hours Only |
| Policy Type | TIME_WINDOW |
| Rule Type | TIME_WINDOW |
| Start Time | 09:00 |
| End Time | 17:00 |
| Action | ALLOW |
Add it in the **Permissions** tab.
If it's currently outside 9am-5pm in your timezone, any payment request will be denied with a
customer-facing schedule reason.
If it's during business hours, you can temporarily set the window to a past range (e.g., 02:00-03:00) to trigger the denial.
Remove the time window policy after testing to avoid blocking your other tests.
Info:
Policy-rule time windows use the server's local time. If you need to test a specific IANA
timezone, configure a wallet-level time window instead.
## Checking Results in Bulk
After running your scenarios, review everything in one place:
### Transactions Page
Go to **Transactions** in the dashboard. You should see:
- Confirmed transactions from approved-and-executed payments
- Denied/rejected entries from the blocked-counterparty and time-window scenarios
- A pending-approval entry for any payment that required approval
### Audit Logs
Go to **Audit Logs** to see the policy evaluation trail for every request. Each entry shows:
- Which policies were evaluated
- Which rules matched
- The final decision and reasoning
### Via API
```bash
# List recent transactions
curl https://conto.finance/api/sdk/transactions \
-H "Authorization: Bearer $CONTO_API_KEY"
```
## Testing x402 Micropayments
If your agent uses x402 protocol payments (paying for APIs), test the pre-authorize → record flow the same way. The request and response shapes are documented in the [x402 SDK reference](https://conto.finance/sdk/x402-payments); the [x402 guide](https://conto.finance/guides/x402-api-payments) covers the end-to-end flow.
## Moving to Production
Once your scenarios pass:
1. Create a production wallet on **Base** (USDC) or **Solana** (USDC)
2. Fund it with real stablecoins
3. Link it to your agent with production-appropriate limits
4. Adjust policies for production thresholds (the test policies can remain as-is)
5. Your integration code stays the same, no code changes needed
Info:
You can keep your testnet wallet and policies active alongside production. Many teams run test
agents permanently for regression testing.
## Troubleshooting
For unexpected policy outcomes (DENIED when you expected REQUIRES_APPROVAL, the wrong policy triggering, org policies overriding agent policies), see the [policy troubleshooting accordions](https://conto.finance/guides/policy-testing#troubleshooting).
Check the **Permissions** tab on the agent detail page. Policies must be explicitly assigned to
the agent. Creating a policy doesn't automatically apply it.
Double-check the timezone setting on the policy. If your local timezone doesn't match the policy
timezone, the enforcement window may be offset.
The wallet balance was sufficient at request time but dropped before execution. This can happen
if other transactions executed between request and execute. Re-fund the testnet wallet.
## Next Steps
### Secure Your Agent
Link: https://conto.finance/guides/securing-agents
Production-ready policy configurations
### Recipes
Link: https://conto.finance/guides/recipes
Copy-paste solutions for specific tasks
### Error Handling
Link: https://conto.finance/sdk/error-handling
Handle every error code gracefully
### Policy Reference
Link: https://conto.finance/policies/overview
All policy types and rule operators