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

> ## Agent Instructions
> When building application code, use `@naturalpay/sdk` for TypeScript or `naturalpay` for Python.
> When operating Natural directly for a user, use the payments MCP at `https://mcp.natural.com`.
> When searching Natural documentation, use the docs MCP at `https://docs.natural.com/mcp`.
> Use the Natural CLI for terminal and CI automation.
> Use REST only for unsupported languages or when the user explicitly requests raw HTTP.
> Start integration development and testing in the sandbox. Do not use production unless the user explicitly requests it.
> For sandbox requests that require `customerPartyId`, list customers first. Reuse only the intended fixture; otherwise create a customer.
> REST and SDK amounts use integer minor units. Payments MCP amounts use decimal strings with a required currency code.

# Test voice in Sandbox

> Create real voice payment outcomes in Sandbox without a phone call, or place a test call from your own phone system

Sandbox lets you exercise the whole voice flow before a real caller does. Every path below creates a real payment intent, a real voice session, and a real card payment (`cpy_*`) in your Sandbox account, with the same events a live call produces.

<Snippet file="shared/prerequisites.mdx" />

## Pick the outcome with the amount

Sandbox never reads a card number to decide an outcome. The cents of the intent amount select it:

| Amount ends in | Outcome                                                     |
| -------------- | ----------------------------------------------------------- |
| `.00`          | Approved                                                    |
| `.07`          | Declined, do not honor (`generic_decline`)                  |
| `.10`          | Declined, invalid card number (`incorrect_card_number`)     |
| `.11`          | Declined, stop all merchants (`stop_payment`)               |
| `.12`          | Declined, stop all future payments (`stop_payment`)         |
| `.13`          | Declined, confirm card data (`generic_decline`)             |
| `.14`          | Declined, stop this payment (`stop_payment`)                |
| `.15`          | Declined, expired card (`card_expired`)                     |
| `.16`          | Declined, new account information (`generic_decline`)       |
| `.17`          | Declined, try again later (`generic_decline`)               |
| `.18` to `.24` | Declined, retry after 1 hour to 10 days (`generic_decline`) |
| `.25`          | Declined, no such issuer (`incorrect_card_number`)          |
| `.26`          | Declined, do not try again (`generic_decline`)              |
| anything else  | Approved                                                    |

`1000` is $10.00 and approves. `1007` is $10.07 and declines. A declined session stays in the call, so you can create a new session on the same intent and try again.

<Snippet file="shared/cents-note.mdx" />

## From the dashboard

Open **Voice** in the Sandbox dashboard and choose **Simulate outcome**. Set the amount, press **Start**, and the results panel shows the session, the payment, and the events as they land. **Test call**, which places a real audio call from your browser, is coming.

## From the API

Three requests, all against your Sandbox base URL with a Sandbox API key.

### 1. Create the payment intent

```bash cURL theme={null}
curl -X POST $NATURAL_API_URL/payment-intents \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "amountMinor": 1000,
        "currency": "USD",
        "description": "Sandbox voice test",
        "taxMode": "exclusive",
        "taxAmountMinor": 0,
        "lineItems": []
      }
    }
  }'
```

Keep the `pmi_*` id from the response.

### 2. Create the voice session

```bash cURL theme={null}
curl -X POST $NATURAL_API_URL/voice/sessions \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "kind": "payment",
        "paymentIntentId": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7"
      }
    }
  }'
```

Keep the `vos_*` id. The session is now awaiting a call.

### 3. Simulate the call

[`POST /simulations/voice/sessions/{voiceSessionId}/call`](/api-reference/simulations/simulate-voice-call) plays the caller and the agent on the server. Natural consumes the session's dial slot, submits a server-owned test card, and applies the outcome the amount selects.

```bash cURL theme={null}
curl -X POST $NATURAL_API_URL/simulations/voice/sessions/vos_019d0a1b2c3d4e5f60718293a4b5c6d8/call \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

<Snippet file="api-examples/simulations.simulateVoiceCall.response.mdx" />

A session accepts one simulated call. A second request with a new `Idempotency-Key` answers `409`. Replaying the same key returns the stored result.

Acting for a customer? Pass their party ID as `customerPartyId` when creating the intent, and as `merchantPartyId` when creating the session and when simulating the call.

Read the result back like any other voice payment: [`GET /payment-intents/{paymentIntentId}`](/api-reference/payment-intents/get-payment-intent) reads `completed` with `"channel": "voice"`, and [`GET /voice/sessions/{voiceSessionId}`](/api-reference/voice/get-voice-session) shows the session. Call facts such as duration and who hung up stay null because no audio call took place.

## From your own phone system

To test the audio path, create the intent and the session as above and dial `dialUri` from your own SIP platform. Before the first call:

* Email [hi@natural.com](mailto:hi@natural.com) the public IP ranges your Sandbox platform signals from, and any `returnTarget` you transfer back to.
* Place the call over SIP with TLS on port 5061, before `dialExpiresAt`.
* Read the amount's cents from the table above to choose the outcome. The card you read to the agent can be any test card.

The full SIP requirements are on the [voice sessions overview](/guides/concepts/voice-sessions#connecting-over-sip).