Pay over Voice

Accept card and ACH payments over the phone with Telnyx Pay over Voice, which collects details via IVR and keeps them out of recordings and AI assistants.

Overview

Telnyx’s Pay over Voice feature enables accepting payments securely over the phone. The feature guides callers through an automated IVR flow to collect payment details (credit card or ACH debit), sends them to the configured payment processor, and returns the result — keeping sensitive card data out of recordings, logs, and AI assistants.

How it works

Caller ←→ Telnyx (IVR + DTMF gather) ←→ Payment Processor
                    │
                    └── Payment events → Webhook / AI assistant

1. Create a Payment Connector pointing to the payment processor’s endpoint.
2. A Pay session is started on an active call (via Voice API, TeXML, or AI Assistant).
3. The caller is guided through IVR prompts to enter payment details via DTMF.
4. Telnyx collects and sends the details to the configured processor endpoint. Use HTTPS to encrypt this connection.
5. The processor charges or tokenizes the payment and returns a result.
6. Telnyx emits progress and completed events to the webhook and AI assistant.

Throughout the session, all processes that could capture payment data — recordings, transcriptions, AI assistant audio, and DTMF logging — are automatically disabled.

---

Create a Payment Connector

A Payment Connector is the bridge between Telnyx and the payment processor. It stores the processor’s endpoint URL and authentication credentials (encrypted at rest with AES-256).

Step 1 — Navigate to Payment Connectors

In the Telnyx Portal, go to Voice API → Applications → Payment Connectors. The portal displays a list of existing connectors:

Each connector shows its name, mode (test or live), type, and creation/update timestamps.

Step 2 — Create a new connector

Click Create Connector. Fill in the following fields:

Field	Required	Description
Connector name	Yes	A unique name for this connector within the organization.
Mode	Yes	test or live. New connectors default to test mode.
Endpoint URL	Yes	The payment processor’s API endpoint. The API accepts HTTP and HTTPS; use HTTPS to protect payment data in transit. Telnyx will POST the payment request here.
Authentication type	Yes	none, basic, or bearer. If basic, provide a username and password. If bearer, provide a token.
Token	Only with bearer	The processor’s bearer token, required when Authentication type is bearer. The token is stored encrypted and never returned in connector responses. Because a connector update that includes config replaces the whole config object, the token must be sent again on every such update.

When Authentication type is set to basic, Telnyx sends the credentials as HTTP Basic Auth headers with each request to the processor. The credentials are encrypted with AES-256-CTR before storage and are never exposed in logs or events.

When Authentication type is set to bearer, Telnyx sends the token in an Authorization: Bearer header with each request to the processor.

Generic connectors can also be managed through the Pay Connectors API. Authenticate these API requests with a Telnyx API key; config.auth_type controls separate authentication from Telnyx to the processor. Set auth_type explicitly (none, basic, or bearer). If omitted, validation requires basic credentials, but the processor request does not acquire a Basic Auth header automatically.

Names are unique within the authenticated organization. Retrieve, update, or delete a connector by its URL-encoded name, not its UUID. Passwords and tokens are omitted from all connector responses; usernames remain visible.

A PATCH containing config replaces the entire configuration. Re-send the endpoint URL and required credentials. A mode-only update omitting config preserves them. Optional config.timeout is the processor HTTP timeout in milliseconds: default 10000, range 1–4294967295. Omit it or supply null in a replacement config to use the default.

# Create a connector
curl -X POST https://api.telnyx.com/v2/pay_connectors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-payment-connector",
    "type": "generic",
    "mode": "test",
    "config": {
      "endpoint_url": "https://api.your-processor.com/v1/payments",
      "auth_type": "basic",
      "username": "merchant_id",
      "password": "your_secret_key"
    }
  }'

# Create a connector with bearer authentication
curl -X POST https://api.telnyx.com/v2/pay_connectors \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-payment-connector",
    "type": "generic",
    "mode": "test",
    "config": {
      "endpoint_url": "https://api.your-processor.com/v1/payments",
      "auth_type": "bearer",
      "token": "<processor-bearer-token>"
    }
  }'

# List connectors
curl https://api.telnyx.com/v2/pay_connectors \
  -H "Authorization: Bearer YOUR_API_KEY"

---

Payment Modes: Test vs Live

Test mode (default)

New connectors default to test mode when mode is omitted. In test mode, the Pay session accepts only a predefined set of test card numbers. Any other card number is rejected with an invalid-card-number error, and the caller is asked to re-enter the number (up to max_attempts times).

For generic connectors, test mode still sends requests to the configured processor URL using the configured credentials. It does not select a processor sandbox or guarantee that no funds move. Use the processor’s sandbox endpoint and credentials for testing.

Valid test card numbers

Card number	Card type
4111111111111111	Visa
5555555555554444	Mastercard
378282246310005	American Express
6011111111111117	Discover
3065930009020004	Diners Club
3566002020360505	JCB
6200000000000005	UnionPay
6771798021000008	Maestro

For ACH-debit test mode, any valid-length routing and account numbers are accepted.

Live mode

Live mode removes the test-card allowlist; normal card validation still applies. The configured processor endpoint and credentials determine where transactions are processed.

The API permits updates and deletion in both modes. Use PATCH /v2/pay_connectors/{name} with {"mode":"live"} to change mode without replacing credentials. Review the processor endpoint and credentials before switching to live.

---

The Payment Process

When a Pay session starts on a call, Telnyx takes over the call leg and guides the caller through a series of IVR steps. Each step plays a voice prompt, then collects the caller’s DTMF input.

Security during payment

Before the first IVR prompt is played, Telnyx automatically disables all processes that could capture payment data:

Process	What happens
Call recordings	All ongoing recordings are masked (audio goes silent). They are automatically resumed when the Pay session ends.
Transcriptions	Transcription audio is silenced by the recording mask. DTMF tones are not captured.
AI assistant connection	DTMF events are suppressed — the AI assistant does not receive keypad input during the Pay session. The assistant receives progress and completed events to track payment status.
DTMF event logging	The sensitive_dtmf flag is set on the channel, preventing FreeSWITCH from logging DTMF digits. DTMF events are not dispatched to webhooks.

IVR steps

The IVR flow depends on the payment method selected:

Credit card flow

Step	Prompt	Digits	Min	Max
1. Card number	”Please enter your credit card number.”	12–19	12	19
2. Expiration date	”Please enter your expiration date. Two digits for the month and two digits for the year.”	4 (MMYY)	4	4
3. Postal code	”Please enter your billing zip code.”	1–10	1	10
4. Security code	”Please enter your security code. It’s the three digits located on the back of your card.”	3–4	3	4
5. Processing	”Your payment is being processed.”	—	—	—

ACH debit flow

Step	Prompt	Digits	Min	Max
1. Routing number	”Please enter your bank routing number.”	9	9	9
2. Account number	”Please enter your bank account number.”	4–17	4	17
3. Processing	”Your payment is being processed.”	—	—	—

Custom prompts

Prompts can be overridden by passing a prompts map. Each key is a step name, and the value is either a string or a list of prompt objects with conditional qualifiers:

{
  "prompts": {
    "payment-card-number": "Please enter the 16-digit number on your card.",
    "expiration-date": "Please enter the expiry date as 4 digits, month first.",
    "postal-code": "Enter your 5-digit billing zip code.",
    "security-code": "Enter the 3-digit code from the back of your card."
  }
}

For conditional prompts (e.g., different message on retry or by card type), use a list of objects:

{
  "prompts": {
    "payment-card-number": [
      { "text": "Please enter your credit card number." },
      { "text": "That card number was not valid. Please try again.", "attempt": "2", "error_type": "invalid-card-number" },
      { "text": "Please enter your Amex card number.", "card_type": "amex" }
    ]
  }
}

Qualifier fields: attempt (1–3), error_type (e.g., invalid-card-number, timeout), card_type (e.g., visa, mastercard, amex, discover).

Error handling and retries

Each step allows up to max_attempts (default 3) retries. If the caller enters too few digits, the wrong format, or times out, the step is repeated with an appropriate error prompt. If all attempts are exhausted, the session ends with too-many-failed-attempts.

Request sent to the payment processor

Once all digits are collected, Telnyx sends a POST to the connector’s endpoint URL with the payment details. The URL determines the transport: HTTPS encrypts the connection; HTTP sends payment details (including card numbers and CVVs) and any processor credentials in plaintext. Configure an HTTPS endpoint; the API does not enforce HTTPS.

Credit card — charge

{
  "method": "charge",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "10.00",
  "currency_code": "USD",
  "description": "Order #12345",
  "cardnumber": "4111111111111111",
  "cvv": "123",
  "expiry_month": "08",
  "expiry_year": "27",
  "postal_code": "94111",
  "parameters": {
    "order_id": "12345",
    "customer_id": "cust_67890"
  }
}

Credit card — tokenize

When transaction_type is tokenize (or amount is 0 or omitted), amount and currency_code are not sent:

{
  "method": "tokenize",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "description": "Save card for future use",
  "cardnumber": "4111111111111111",
  "cvv": "123",
  "expiry_month": "08",
  "expiry_year": "27",
  "postal_code": "94111",
  "parameters": {}
}

ACH debit — charge

{
  "method": "charge",
  "transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "10.00",
  "currency_code": "USD",
  "description": "Order #12345",
  "bankaccountnumber": "1234567890",
  "routingnumber": "021000021",
  "parameters": {}
}

Response expected from the payment processor

The processor should return a JSON response:

Charge — success:

{
  "charge_id": "ch_abc123",
  "error_code": null,
  "error_message": null
}

Tokenize — success:

{
  "token_id": "tok_abc123",
  "error_code": null,
  "error_message": null
}

Error:

{
  "error_code": "card_declined",
  "error_message": "The card was declined."
}

Return a successful HTTP status with a JSON object. For a business failure, include both error_code (non-null and non-empty) and error_message; the session ends with payment-connector-error. A charge success requires a non-empty string charge_id; tokenization requires a non-empty string token_id. Transport timeouts and non-success HTTP statuses are processor failures, not successful payments.

---

Using Pay over Voice

Pay over Voice can be triggered from three interfaces: the Voice API, TeXML, and AI Assistant.

Voice API

Start a Pay session by sending a POST request to the pay endpoint on an active call:

curl -X POST https://api.telnyx.com/v2/calls/{call_control_id}/actions/pay \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connector_name": "my-payment-connector",
    "amount": "10.00",
    "currency": "USD",
    "payment_method": "credit-card",
    "description": "Order #12345"
  }'

Request parameters

Parameter	Type	Default	Description
connector_name	string	"Default"	Name of the payment connector to use.
amount	decimal	—	Charge amount. Omit or set to 0 for tokenize. Required for charge.
currency	string	"USD"	ISO 4217 currency code.
payment_method	string	"credit-card"	credit-card or ach-debit.
transaction_type	string	auto	charge or tokenize. Auto-detected from amount if omitted.
payment_token	string	—	A previously obtained token for charging a saved card. Skips IVR and processes directly.
description	string	—	Description sent to the processor and included in events.
metadata	object	{}	Arbitrary key-value metadata.
parameters	object	{}	Custom parameters sent to the processor in the parameters field.
prompts	object	{}	Custom IVR prompts (see Custom prompts).
max_attempts	integer	3	Max retry attempts per step (1–3).
timeout_millis	integer	5000	Timeout per gather in milliseconds (1–600000).
inter_digit_timeout_millis	integer	5000	Timeout between digits in milliseconds (1–600000).
voice	string	"female"	TTS voice for prompts.
language	string	"en-US"	Language for prompts.
service_level	string	"premium"	TTS service level.
client_state	string	—	Base64 client state, echoed back in webhook events.

TeXML

Use the <Pay> verb in a TeXML application. This is the simplest way to start a Pay session — include the verb in the TeXML response and Telnyx handles the rest:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Pay chargeAmount="10.00"
       paymentConnector="my-payment-connector"
       currency="USD"
       paymentMethod="credit-card" />
</Response>

For tokenization (no charge):

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Pay paymentConnector="my-payment-connector"
       paymentMethod="credit-card" />
</Response>

As the Pay session progresses, Telnyx sends webhook callbacks to the TeXML application’s webhook URL with call_payment_progress and call_payment_completed events. The application can use these to update external systems, confirm the payment, or continue the call flow.

AI Assistant

When using Telnyx’s AI Voice Assistant, a Pay tool can be added to the assistant so it can trigger a payment session during a conversation.

In the AI Assistant configuration, click Add Pay Tool (BETA) and configure:

Field	Required	Description
Connector Name	Yes	The payment connector to use.
Currency	Yes	ISO 4217 currency code (e.g., USD).
Payment Method	Yes	credit-card or ach-debit.
Description	No	Tool description shown to the assistant so it knows when to collect a payment. Not sent to the payment connector — the description argument the assistant passes when calling the tool is what reaches the processor.
Timeout	No	Tool execution timeout in milliseconds (default 5000).

Further fields are available through the Assistant API but not in the Portal form:

Field	Required	Description
connector_parameters	No	Custom key/value parameters forwarded to the pay connector as parameters in the processor request. String values may use {{dynamic_variable}} templating, resolved per call.
valid_card_types	No	Restricts accepted card numbers to the listed card types (visa, mastercard, amex, maestro, discover, optima, jcb, diners-club, enroute). When the caller enters a card number that does not match, Pay treats the input as invalid and re-prompts for the card number.
postal_code	No	Controls billing postal code collection for credit-card payments. Set to false to skip the postal code prompt without supplying a postal code to the payment connector (for non-US cards, e.g. Irish Eircodes). Set to true to prompt the caller. Supply a non-empty string, such as "90210", to use that postal code without prompting. Does not affect ACH debit payments or payments using an existing token.
min_postal_code_length	No	Minimum digits (1–128) the caller must enter when collecting a credit-card billing postal code. Omitted means the platform default (1) applies.
max_attempts	No	Maximum attempts (1–3) per collection step. Omitted means the platform default (3) applies.
timeout_millis	No	Time in milliseconds (1–600000) to wait for DTMF input for each collection step. Omitted means the platform default (5000) applies — increase it for slower entry, e.g. a 16-digit card number.
inter_digit_timeout_millis	No	Time in milliseconds (1–600000) to wait between consecutive DTMF digits. Omitted means the platform default (5000) applies.
prompts	No	Custom IVR prompts keyed by collection step (payment-card-number, expiration-date, postal-code, security-code, bank-routing-number, bank-account-number), following the same shape as the Voice API’s prompts: each value is a prompt string or a list of {text, attempt, error_type, card_type} objects. Unknown step keys, unknown error_type/card_type values, and prompts qualified with an attempt number above max_attempts are rejected at save time. The assistant merges its own card-number prompt into this map, so a per-step prompt you set here wins over the assistant’s default.

When the AI assistant invokes the Pay tool, it starts a Pay session on the call. The assistant receives call.payment.progress events after each IVR step and a call.payment.completed event with the final result. This lets the assistant inform the caller of the payment status and continue the conversation naturally.

:::note During the Pay session, the AI assistant does not receive DTMF input or audio from the caller. The assistant only receives progress and completion events with masked payment data. This ensures the assistant never has access to raw card numbers, CVVs, or bank account details. :::

---

Events

Two events are emitted during a Pay session. Both are sent to the configured webhook URL and, if active, to the AI assistant.

Payment Progress

Sent after each IVR step completes or fails. Event name: call.payment.progress (API v2) or call_payment_progress (TeXML).

{
  "event_type": "call.payment.progress",
  "occurred_at": "2026-07-20T20:30:00.000Z",
  "payment_connector": "my-payment-connector",
  "payment_method": "credit-card",
  "payment_step": "payment-card-number",
  "payment_status": "completed",
  "attempt": 1,
  "error_type": null,
  "payment_card_type": "visa",
  "payment_card_number": "xxxxxxxxxxxx1111",
  "expiration_date": null,
  "security_code": null,
  "payment_card_postal_code": null
}

Accumulated masked payment data is included from all previously completed steps. Card numbers are masked to show only the last 4 digits. Security codes are fully masked (xxx).

Payment Completed

Sent when the Pay session ends (success, failure, or cancellation). Event name: call.payment.completed (API v2) or call_payment_completed (TeXML).

Success:

{
  "event_type": "call.payment.completed",
  "occurred_at": "2026-07-20T20:31:15.000Z",
  "payment_connector": "my-payment-connector",
  "payment_method": "credit-card",
  "result": "success",
  "payment_card_type": "visa",
  "payment_card_number": "xxxxxxxxxxxx1111",
  "expiration_date": "0827",
  "security_code": "xxx",
  "payment_card_postal_code": "94111",
  "charge_id": "ch_abc123",
  "payment_error": null,
  "pay_error_code": null
}

Failure:

{
  "event_type": "call.payment.completed",
  "occurred_at": "2026-07-20T20:31:15.000Z",
  "payment_connector": "my-payment-connector",
  "payment_method": "credit-card",
  "result": "payment-connector-error",
  "payment_card_type": "visa",
  "payment_card_number": "xxxxxxxxxxxx1111",
  "payment_error": "connector_error",
  "pay_error_code": "card_declined",
  "connector_error": { "error_code": "card_declined", "error_message": "The card was declined." }
}

Result values

Result	Description
success	Payment was processed successfully. charge_id or token_id is included.
cancelled	Caller hung up or the call was cancelled during the session.
too-many-failed-attempts	A step failed more than max_attempts times.
payment-connector-error	The processor returned an error, was unreachable, or the connector was not found.
internal-error	Unexpected response from the processor (e.g., missing charge_id or token_id).

---

Quick reference

Endpoints

Method	Path	Description
POST	/v2/pay_connectors	Create a generic connector
GET	/v2/pay_connectors	List connectors
GET	/v2/pay_connectors/{name}	Retrieve a connector
PATCH	/v2/pay_connectors/{name}	Update a generic connector
DELETE	/v2/pay_connectors/{name}	Delete a connector
POST	/v2/calls/{call_control_id}/actions/pay	Start a Pay session

Transaction types

Type	When	Behavior
charge	amount > 0	Captures funds immediately. Processor must return charge_id.
tokenize	amount = 0 or omitted	Obtains a token for future charges. Processor must return token_id.