Sign in

v52

OpenAPI 3.1.0raw.githubusercontent.com2026-07-311,1941,9384.1 MB
Call Commands

Collect payment details

Collect payment details from the caller using DTMF and either charge or tokenize the payment method through a configured Pay connector. Pay pauses active call recordings while sensitive payment details are collected.

When payment_token is supplied, the DTMF collection steps are skipped and the existing token is sent to the connector.

Expected Webhooks:

  • call.payment.progress
  • call.payment.completed

Test mode card numbers: 4111111111111111 (Visa), 5555555555554444 (Mastercard), 378282246310005 (American Express), 6011111111111117 (Discover), 3065930009020004 (Diners Club), 3566002020360505 (JCB), 6200000000000005 (UnionPay), and 6771798021000008 (Maestro). Test-mode connectors reject other card numbers before contacting the configured processor. The UnionPay and Maestro numbers are accepted for processor testing, but Pay currently does not emit a card type for them.

post/calls/{call_control_id}/actions/pay

Path parameters

call_control_idstring required

Unique identifier and token for controlling the call

Request body

amountnumber

Amount to charge. Required when transaction_type is charge.

client_statestring

Base64-encoded state included in subsequent webhooks.

command_idstring

Idempotency key for the command. Telnyx ignores a duplicate command with the same command_id for the same call_control_id.

connector_namestring

Name of the Pay connector used to process the transaction.

currency'USD' | 'usd'

Currency used for the transaction. Pay currently supports USD only.

descriptionstring

Optional description forwarded with the payment transaction.

inter_digit_timeout_millisinteger

Time in milliseconds to wait between consecutive DTMF digits.

languagestring

Language used for payment prompts.

max_attemptsinteger

Maximum number of attempts for each payment collection step.

metadataobject

Metadata forwarded to the Pay connector.

parametersobject

Additional parameters forwarded to the Pay connector.

payment_method'credit-card' | 'ach-debit'

Payment method to collect.

payment_tokenstring

Existing payment token. When supplied, payment-detail collection is skipped.

service_levelstring

Speech synthesis service level used for payment prompts. Pay defaults to premium.

timeout_millisinteger

Time in milliseconds to wait for DTMF input for each collection step.

transaction_type'charge' | 'tokenize'

Transaction to perform. If omitted, Pay infers tokenize when amount is absent or zero and charge when amount is positive.

voicestring

Voice used for payment prompts. Accepts male, female, or a provider voice in <Provider>.<Model>.<VoiceId> format, for example AWS.Polly.Joanna or Telnyx.KokoroTTS.af.

Example request

{
  "amount": 10.5,
  "client_state": "aGF2ZSBhIG5pY2UgZGF5ID1d",
  "command_id": "891510ac-f3e4-11e8-af5b-de00688a4901",
  "connector_name": "Default",
  "currency": "USD",
  "inter_digit_timeout_millis": 5000,
  "language": "en-US",
  "max_attempts": 3,
  "payment_method": "credit-card",
  "timeout_millis": 5000,
  "transaction_type": "charge",
  "voice": "female"
}

Response

Successful response upon making a call control command.

Example response

{
  "data": {
    "result": "ok"
  }
}