> ## 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 with [`POST /voice/sessions`](/api-reference/voice/create-voice-session), transfer the caller to the SIP URI it returns, and Natural's agent takes the card. The payment intent (`pmi_*`) is the payment record; the session is the call. A card payment (`cpy_*`) records each attempt. See [Take a payment over voice](/guides/voice/take-a-payment).

```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 until `dialExpiresAt` (15 minutes from creation, or the intent's `expiresAt` if sooner) and accepts one call. If the 30-minute call limit passes without a recorded call end, the session shows `expired`. Natural's agent names the business, reads the total from the intent, and collects the card number, expiry, security code, and billing ZIP and country by speech or keypad. Card data goes from the call to Natural and never reaches your systems, which keeps 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, Natural's agent asks the caller to re-read it or try another card. After three failed attempts on the intent (sooner for some declines), and only when you set `callerPhone`, Natural texts the caller a checkout link for the same intent. A decline that signals fraud ends the call without a link.

## Lifecycle

A session is `awaitingCall` while it can be dialed. It becomes `inProgress` when the call starts. It becomes `ended` when the provider reports the call end, regardless of the payment outcome.

A session is `canceled` when a newer session replaces it. It is `expired` when the dial window or call time limit passes without a recorded end. It is `failed` when the voice session fails.

Payment approval, decline, and checkout-link delivery do not determine the call status. Read the linked payment intent for the payment outcome.

## 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 passes 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 voice sessions](/api-reference/voice/list-voice-sessions) is the call log. [Get a voice session](/api-reference/voice/get-voice-session) returns when the call started and ended, its duration, who hung up (`call.endedBy`: `caller`, `assistant`, `unknown`, or null while the call is open), and a short summary. [Get the transcript](/api-reference/voice/get-voice-session-transcript) fetches it on demand. Natural never stores it, and every run of digits is masked. The payment itself is on the intent. See [Call log and transcripts](/guides/voice/call-log).

## Access

Creating a session requires both `voice_sessions.create` and `payment_intents.create`, plus Accept and Voice enabled on the account. Reads and transcripts require `voice_sessions.read`, which `voice_sessions.create` includes. Pass `customerPartyId` in the create body, or as a query parameter on reads, when acting for a customer.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.