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

​
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 for the call log. Get a session for when it started and ended, its duration, who hung up, and a short summary. The 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.