Sign in
Call Commands

Process a payment

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

connector_namestring

Name of the Pay connector used to process the transaction.

amountnumber

Amount to charge. Required when transaction_type is charge.

currency'USD' | 'usd'

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

payment_tokenstring

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

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

Payment method to collect.

valid_card_typesstring[]

Restricts accepted card numbers to the listed card types. When the caller enters a card number that does not match one of the listed types, Pay treats the input as invalid and re-prompts for the card number. Cannot be used together with payment_token.

transaction_type'charge' | 'tokenize'

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

descriptionstring

Optional description forwarded with the payment transaction.

client_statestring

Base64-encoded state included in subsequent webhooks.

metadataobject

Metadata forwarded to the Pay connector.

parametersobject

Additional parameters forwarded to the Pay connector.

max_attemptsinteger

Maximum number of attempts for each payment collection step.

timeout_millisinteger

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

inter_digit_timeout_millisinteger

Time in milliseconds to wait between consecutive DTMF digits.

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.

languagestring

Language used for payment prompts.

service_levelstring

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

command_idstring

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

Example request

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

Response

Successful response upon making a call control command.

Example response

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

Changes

Changed in 4 of the 99 revisions of this API.726

  • a6a61a29ecdd25See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the new enroute enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new enroute enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new enroute enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new enroute enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new enroute enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new enroute enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new invalid-card-type enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new invalid-card-type enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new invalid-card-type enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new invalid-card-type enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new invalid-card-type enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new invalid-card-type enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new maestro enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new maestro enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new maestro enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new maestro enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new maestro enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new maestro enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new optima enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new optima enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new optima enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new optima enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new optima enum value to the request property ////

      request-property-enum-value-added

    • ○

      added the new optima enum value to the request property ////

      request-property-enum-value-added

    This revision also has 34 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 1571b0380bd73See the full diff
    • ▲

      the response's body type changed from object to no type for status

      response-body-type-changed

    • ▲

      the / response's property type changed from object to no type for status

      response-property-type-changed

    • ▲

      the // response's property type changed from integer to string, and format from int32 to integer for status

      response-property-type-changed

    This revision also has 64 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 8f5f4e5379944See the full diff
    • ▲

      the response's body type changed from no type to object for status

      response-body-type-changed

    • ▲

      the / response's property type changed from no type to object for status

      response-property-type-changed

    • ▲

      the // response's property type changed from string to integer, and format from integer to int32 for status

      response-property-type-changed

    • ▲

      the /// response's property format changed from json-pointer to no format for status

      response-property-type-changed

    This revision also has 41 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 2e781c41fbcd1See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

Of the 99 revisions, 1 has no diff computed.