Test voice in Sandbox

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.

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.

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

cURL

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

cURL

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

cURL

curl -X POST $NATURAL_API_URL/simulations/voice/sessions/vos_019d0a1b2c3d4e5f60718293a4b5c6d8/call \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

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} reads completed with "channel": "voice", and GET /voice/sessions/{voiceSessionId} 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 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.

Overview

Common use cases

Products

Guides

Pick the outcome with the amount

From the dashboard

From the API

1. Create the payment intent

2. Create the voice session

3. Simulate the call

From your own phone system

​Pick the outcome with the amount

​From the dashboard

​From the API

​1. Create the payment intent

​2. Create the voice session

​3. Simulate the call

​From your own phone system

Pick the outcome with the amount

From the dashboard

From the API

1. Create the payment intent

2. Create the voice session

3. Simulate the call

From your own phone system