Skip to main content
Voice is in early access and subject to change. To request Voice access, contact hi@natural.com.
A voice session (vos_*) collects one open payment intent over one phone call. You create the session with POST /voice/sessions, 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.

​
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 is the call log. Get a 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 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.

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