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

# Overview

> Collect a payment intent over a phone call with a single SIP transfer

<Note>
  Voice is in early access and subject to change. To request Voice access, contact [hi@natural.com](mailto:hi@natural.com).
</Note>

A voice session (`vos_*`) collects one open [payment intent](/guides/concepts/payment-intents) over one phone call. You create the session, transfer the caller to the SIP URI it returns, and Natural's agent takes the card. The intent is the payment record; the session is the call.

```json theme={null}
{
  "data": {
    "attributes": {
      "kind": "payment",
      "paymentIntentId": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
      "callerPhone": "+14155550123",
      "returnTarget": "sip:agent-9920@sip.partner.example.com"
    }
  }
}
```

## The call

A session is dialable for 15 minutes and accepts one call. Natural's agent names the business, reads the total from the intent, and collects the card number, expiry, security code, and billing ZIP by speech or keypad. Card data goes straight from the call to being processed by Natural and never reaches your systems to keep you out of PCI-DSS scope. When the call ends, Natural transfers the call to your `returnTarget` with the caller on it, or hangs up if you did not set one.

If the card is refused, the agent retries on the same call, and after three refusals texts the caller a checkout link for the same intent.

## Status

`in_progress` while the call is pending or under way. `completed` when the card was approved. `declined` when the last attempt was refused. `payment_link_sent` when Natural texted the checkout link instead. `cancelled` when a newer session replaced this one or the call ended without a payment. `expired` when nobody dialed in time. `failed` when an error ended the session.

## Connecting over SIP

Natural admits calls only from IP ranges it knows. Place the call to `dialUri` over SIP with TLS on port 5061. Natural relays the signaling to its agent; audio flows directly between your platform and Natural's agent.

A `returnTarget` must accept SIP over TLS with a certificate from a public Certificate Authority, and take media directly from Natural's agent.

## Reading a session

[List sessions](/api-reference/voice/list-voice-sessions) for the call log. [Get a session](/api-reference/voice/get-voice-session) for when it started and ended, its duration, who hung up, and a short summary. The [transcript](/api-reference/voice/get-voice-session-transcript) comes from the voice provider on demand, is never stored by Natural, and has every run of digits masked. The payment itself is on the intent.