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 returneddialUri, 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 topaymentIntent.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.failureholds the last decline, if any.unpaid: the call ended without a payment or a link.
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.
completed. Its cardPayment relationship identifies the successful payment.