> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Testing Payments Safely

> Validate your integration on testnet, simulate policy outcomes, and test edge cases without risking real funds

# 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](/guides/policy-testing).

## Prerequisites

<Check>An agent with an SDK key ([Quickstart](/quickstart/setup)), or an agent sandbox (below)</Check>
<Check>For testnet scenarios: a funded Tempo Testnet wallet linked to your agent</Check>

## 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-mode organization, agent, Tempo Testnet wallet, and SDK keys in one call, with no email verification or human approval. Sandbox payments execute in **simulated** mode: policy evaluation, spend tracking, receipts, and audit logs are real, but no onchain transfer happens, so you don't need a signer or a funded wallet.

See the [Agent Sandbox Quickstart](/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 code stays the same when you switch to production. Only the wallet and chain change. The [Quickstart](/quickstart/setup) covers creating and funding a testnet wallet.

## 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](/guides/webhooks) to get notified). For handling `DENIED` and `REQUIRES_APPROVAL` statuses in code, see [Error Handling](/sdk/error-handling#using-request-and-execute-for-better-control).

## Scenario 1: Blocked Counterparty

First create and assign the policy:

<Steps>
  <Step title="Create the policy">
    Go to **Policies** → **New Policy**.

    | Field       | Value                 |
    | ----------- | --------------------- |
    | Name        | Test: Blocked Address |
    | Policy Type | COUNTERPARTY          |
  </Step>

  <Step title="Add rule">
    | Field     | Value                                       |
    | --------- | ------------------------------------------- |
    | Rule Type | BLOCKED\_COUNTERPARTIES                     |
    | Value     | `0xBLOCKED0000000000000000000000000000dead` |
    | Action    | DENY                                        |
  </Step>

  <Step title="Assign it to your agent">
    Add it in the **Permissions** tab.
  </Step>
</Steps>

Then send a \$5 payment to the blocked address:

```bash theme={null}
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"`
* `violations` reference the blocked counterparty policy
* 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:

<Steps>
  <Step title="Create 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                     |
  </Step>

  <Step title="Assign it to your agent">
    Add it in the **Permissions** tab.
  </Step>

  <Step title="Test outside the window">
    If it's currently outside 9am-5pm in your timezone, any payment request will be denied with a time window violation.

    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.
  </Step>

  <Step title="Clean up">
    Remove the time window policy after testing to avoid blocking your other tests.
  </Step>
</Steps>

<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.
</Info>

## 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 theme={null}
# 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](/sdk/x402-payments); the [x402 guide](/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.
</Info>

## 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](/guides/policy-testing#troubleshooting).

<AccordionGroup>
  <Accordion title="All scenarios return APPROVED (policies not enforcing)">
    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.
  </Accordion>

  <Accordion title="Time window tests pass when they shouldn't">
    Double-check the timezone setting on the policy. If your local timezone doesn't match the policy timezone, the enforcement window may be offset.
  </Accordion>

  <Accordion title="Execute returns INSUFFICIENT_BALANCE after approval">
    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.
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Secure Your Agent" icon="shield" href="/guides/securing-agents">
    Production-ready policy configurations
  </Card>

  <Card title="Recipes" icon="book-open" href="/guides/recipes">
    Copy-paste solutions for specific tasks
  </Card>

  <Card title="Error Handling" icon="bug" href="/sdk/error-handling">
    Handle every error code gracefully
  </Card>

  <Card title="Policy Reference" icon="list-check" href="/policies/overview">
    All policy types and rule operators
  </Card>
</CardGroup>