Take a payment over voice

Voice allows you to take card payments in a PCI compliant manner. Voice agents typically run cloud hosted LLMs, telephony, STT/TTS, and logging, making cardholder data infamously hard to capture due to PCI-DSS standards. Voice runs a locally hosted PCI-compliant voice agent that allows inbound SIP transfers to make voice payments on. It can be configured to transfer back to the original call or ended upon completion, with redacted transcripts available and realtime webhooks. Transfer the caller to Natural’s agent. It takes the card and processes the payment while your systems stay out of PCI scope. 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.

import uuid
from naturalpay import Natural

# Set NATURAL_API_KEY to your agent's API key.
client = Natural(instance_id=str(uuid.uuid4()))

session = client.voice_sessions.create(
    kind="payment",
    payment_intent_id="pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
    caller_phone="+14155550123",
    return_target="sip:agent-9920@sip.partner.example.com",
    idempotency_key=str(uuid.uuid4()),
)

import Natural from "@naturalpay/sdk";

// Set NATURAL_API_KEY to your agent's API key.
const client = new Natural();
const session = await client.voiceSessions.create(
  {
    kind: "payment",
    paymentIntentId: "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
    callerPhone: "+14155550123",
    returnTarget: "sip:agent-9920@sip.partner.example.com",
    idempotencyKey: crypto.randomUUID(),
  },
  { instanceId: crypto.randomUUID() },
);

natural voice-sessions create \
  --kind payment \
  --payment-intent-id pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 \
  --caller-phone +14155550123 \
  --return-target sip:agent-9920@sip.partner.example.com \
  --x-instance-id "$(uuidgen)" \
  --idempotency-key "$(uuidgen)"

Create a voice session for payment intent pmi_019d0a1b2c3d4e5f60718293a4b5c6d7.
The caller is +14155550123. Return the call to sip:agent-9920@sip.partner.example.com.

# NATURAL_API_KEY=ak_ntl_prod_... (the agent's key)
curl -X POST https://api.natural.com/voice/sessions \
  -H "Authorization: Bearer $NATURAL_API_KEY" \
  -H "X-Instance-ID: $(uuidgen)" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "attributes": {
        "kind": "payment",
        "paymentIntentId": "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
        "callerPhone": "+14155550123",
        "returnTarget": "sip:agent-9920@sip.partner.example.com"
      }
    }
  }'

callerPhone is required. Natural texts that number a checkout link if the card keeps failing. Set returnTarget to the SIP address that receives the call afterward, or omit it to hang up.

Transfer the caller

Transfer the call over SIP to the returned dialUri 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. 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 voice_session_in_call. 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.

payment = client.payment_intents.get(
    "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
)

const payment = await client.paymentIntents.get({
  paymentIntentId: "pmi_019d0a1b2c3d4e5f60718293a4b5c6d7",
});

natural payment-intents get --payment-intent-id pmi_019d0a1b2c3d4e5f60718293a4b5c6d7

Has that voice payment completed?

curl https://api.natural.com/payment-intents/pmi_019d0a1b2c3d4e5f60718293a4b5c6d7 \
  -H "Authorization: Bearer $NATURAL_API_KEY"

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.

Overview

Common use cases

Guides

Take a payment over voice

Create the voice session

Transfer the caller

Read the result

​Create the voice session

​Transfer the caller

​Read the result

Create the voice session

Transfer the caller

Read the result