---
title: "Collect payment details"
method: POST
path: "/calls/{call_control_id}/actions/pay"
tags: ["Call Commands"]
---

# Collect payment details

`POST /calls/{call_control_id}/actions/pay`

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.

## Path parameters

- `call_control_id` string, required

## Request body

- PayRequest
  - `connector_name` string — Name of the Pay connector used to process the transaction.
  - `amount` number — Amount to charge. Required when `transaction_type` is `charge`.
  - `currency` 'USD' | 'usd' — Currency used for the transaction. Pay currently supports USD only.
  - `payment_token` string — Existing payment token. When supplied, payment-detail collection is skipped.
  - `payment_method` 'credit-card' | 'ach-debit' — Payment method to collect.
  - `transaction_type` 'charge' | 'tokenize' — Transaction to perform. If omitted, Pay infers `tokenize` when `amount` is absent or zero and `charge` when `amount` is positive.
  - `description` string — Optional description forwarded with the payment transaction.
  - `client_state` string — Base64-encoded state included in subsequent webhooks.
  - `metadata` object — Metadata forwarded to the Pay connector.
  - `parameters` object — Additional parameters forwarded to the Pay connector.
  - `prompts` PayPrompts — Custom text-to-speech prompts keyed by payment collection step.
    - `payment-card-number` union — A default prompt string or an ordered list of qualified prompts.
      - string
      - PayPrompt[]
        - `text` string, required — Text spoken for the payment collection step.
        - `attempt` string — Space-separated 1-based attempt numbers for which this prompt applies.
        - `error_type` 'timeout' | 'invalid-card-number' | 'invalid-date' | 'invalid-security-code' | 'invalid-postal-code' | 'invalid-bank-routing-number' | 'invalid-bank-account-number' | 'input-matching-failed' — Step error for which this prompt applies.
        - `card_type` 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners-club' | 'jcb' — Lowercase, case-sensitive detected card type for which this prompt applies. Only the listed brands are currently detected; accepted UnionPay and Maestro test cards do not produce a card-type qualifier.
    - `expiration-date` union — A default prompt string or an ordered list of qualified prompts.
      - string
      - PayPrompt[]
        - `text` string, required — Text spoken for the payment collection step.
        - `attempt` string — Space-separated 1-based attempt numbers for which this prompt applies.
        - `error_type` 'timeout' | 'invalid-card-number' | 'invalid-date' | 'invalid-security-code' | 'invalid-postal-code' | 'invalid-bank-routing-number' | 'invalid-bank-account-number' | 'input-matching-failed' — Step error for which this prompt applies.
        - `card_type` 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners-club' | 'jcb' — Lowercase, case-sensitive detected card type for which this prompt applies. Only the listed brands are currently detected; accepted UnionPay and Maestro test cards do not produce a card-type qualifier.
    - `postal-code` union — A default prompt string or an ordered list of qualified prompts.
      - string
      - PayPrompt[]
        - `text` string, required — Text spoken for the payment collection step.
        - `attempt` string — Space-separated 1-based attempt numbers for which this prompt applies.
        - `error_type` 'timeout' | 'invalid-card-number' | 'invalid-date' | 'invalid-security-code' | 'invalid-postal-code' | 'invalid-bank-routing-number' | 'invalid-bank-account-number' | 'input-matching-failed' — Step error for which this prompt applies.
        - `card_type` 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners-club' | 'jcb' — Lowercase, case-sensitive detected card type for which this prompt applies. Only the listed brands are currently detected; accepted UnionPay and Maestro test cards do not produce a card-type qualifier.
    - `security-code` union — A default prompt string or an ordered list of qualified prompts.
      - string
      - PayPrompt[]
        - `text` string, required — Text spoken for the payment collection step.
        - `attempt` string — Space-separated 1-based attempt numbers for which this prompt applies.
        - `error_type` 'timeout' | 'invalid-card-number' | 'invalid-date' | 'invalid-security-code' | 'invalid-postal-code' | 'invalid-bank-routing-number' | 'invalid-bank-account-number' | 'input-matching-failed' — Step error for which this prompt applies.
        - `card_type` 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners-club' | 'jcb' — Lowercase, case-sensitive detected card type for which this prompt applies. Only the listed brands are currently detected; accepted UnionPay and Maestro test cards do not produce a card-type qualifier.
    - `bank-routing-number` union — A default prompt string or an ordered list of qualified prompts.
      - string
      - PayPrompt[]
        - `text` string, required — Text spoken for the payment collection step.
        - `attempt` string — Space-separated 1-based attempt numbers for which this prompt applies.
        - `error_type` 'timeout' | 'invalid-card-number' | 'invalid-date' | 'invalid-security-code' | 'invalid-postal-code' | 'invalid-bank-routing-number' | 'invalid-bank-account-number' | 'input-matching-failed' — Step error for which this prompt applies.
        - `card_type` 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners-club' | 'jcb' — Lowercase, case-sensitive detected card type for which this prompt applies. Only the listed brands are currently detected; accepted UnionPay and Maestro test cards do not produce a card-type qualifier.
    - `bank-account-number` union — A default prompt string or an ordered list of qualified prompts.
      - string
      - PayPrompt[]
        - `text` string, required — Text spoken for the payment collection step.
        - `attempt` string — Space-separated 1-based attempt numbers for which this prompt applies.
        - `error_type` 'timeout' | 'invalid-card-number' | 'invalid-date' | 'invalid-security-code' | 'invalid-postal-code' | 'invalid-bank-routing-number' | 'invalid-bank-account-number' | 'input-matching-failed' — Step error for which this prompt applies.
        - `card_type` 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners-club' | 'jcb' — Lowercase, case-sensitive detected card type for which this prompt applies. Only the listed brands are currently detected; accepted UnionPay and Maestro test cards do not produce a card-type qualifier.
  - `max_attempts` integer — Maximum number of attempts for each payment collection step.
  - `timeout_millis` integer — Time in milliseconds to wait for DTMF input for each collection step.
  - `inter_digit_timeout_millis` integer — Time in milliseconds to wait between consecutive DTMF digits.
  - `voice` string — 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`.
  - `language` string — Language used for payment prompts.
  - `service_level` string — Speech synthesis service level used for payment prompts. Pay defaults to `premium`.
  - `command_id` string — Idempotency key for the command. Telnyx ignores a duplicate command with the same `command_id` for the same `call_control_id`.

## Response `200`

Successful response upon making a call control command.

- object
  - `data` CallControlCommandResult
    - `result` string

## Other responses

- `422` — Unprocessable entity. The request was well-formed but could not be processed due to semantic errors. This includes validation errors, invalid parameter values, call state errors, conference errors, queue errors, recording/transcription errors, and business logic violations.
- `default` — Unexpected error

---

[API](https://skmtc.net/team-telnyx/apis/telnyx-api-2.md) · [All operations](https://skmtc.net/team-telnyx/apis/telnyx-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/team-telnyx/telnyx-api-2/versions/8f5f4e537994/schema)