Skip to main content
Hand the caller to Natural’s agent, which takes the card and charges it, so card details never reach your agent, recordings, transcripts, or servers. When it’s done, Natural transfers the caller back to you or hangs up. Transcripts are redacted, and webhooks report each outcome. Before you start, connect Natural to your agent or create an API key. See Start here. Setup takes a couple of minutes; the MCP path needs no API key. Complete Accept onboarding, then contact hi@natural.com to connect your voice platform. A merchant that accepts cards is ready for voice. Read more: Payments over Voice.
Collecting for a customer? Pass their party ID as customerPartyId when creating the payment intent and voice session.

Create the voice session

Create a payment intent, then create a voice session for it.
When an agent (agt_*) creates, cancels, fulfills, or declines a payment, payment request, transfer, payment intent, refund, or voice session, it authenticates with its own credential (an agent key or an agent-scoped OAuth grant) and names the run with the X-Instance-ID header. Without it the call returns 400 missingInstanceId. Reads don’t need it.
callerPhone is required. Natural texts that number a checkout link after three failed attempts, or sooner for some declines. A decline that signals fraud ends the call without a link. Set returnTarget to the SIP address that receives the call afterward, or omit it to hang up.

Transfer the caller

Hand the caller off with a blind SIP transfer to the returned dialUri, as described in Connect your phone system. Transfer before dialExpiresAt, which is 15 minutes after creation or sooner if the intent expires first. Natural’s agent confirms the amount, takes the card by speech or keypad, and processes the payment. dialUri is opaque and ends in ;transport=tls. Store it from the create response and dial it exactly as returned, except on Telnyx, where you swap only the host as in Connect Telnyx. Each session accepts one call. Create a new session if the transfer fails or the session expires. While a call on the same payment intent is live, create answers 409 with code voiceSession.inCall. It works again once that call ends.

Read the result

Get the payment intent to check its status, or subscribe to paymentIntent.completed, cardPayment.succeeded, and cardPayment.failed webhooks. Subscribe to voiceSession.completed to learn how each session finished. One event ends every session, sent exactly once. Its status is ended, expired, or canceled. canceled and expired can arrive a few minutes after the fact. The event carries the call details. It does not mean paid. Read payment.outcome:
  • paid: the card was charged on the call.
  • linkSent: voice payment did not succeed, so Natural texted the caller the checkout link. The payment intent stays open. payment.failure holds the last decline, if any.
  • unpaid: the call ended without a payment or a link.
A paid call whose call end never reached Natural closes as expired with outcome paid, so read the outcome, not the status. The payment intent is the source of truth for money. Webhook delivery order is not guaranteed, so do not rely on voiceSession.completed arriving before or after the payment events. A later link payment arrives as paymentIntent.completed. The voice session’s outcome stays linkSent. The outcome is on the voice session as soon as it is known, before the call ends. Get the voice session if you need it before the event.
A paid intent has status completed. Its cardPayment relationship identifies the successful payment.
View call logs and transcripts in the dashboard or through the API, with card details redacted. See Call log and transcripts.