> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pay

The `<Pay>` verb collects payment information from a caller using DTMF and either charges or tokenizes the payment method through a configured Pay connector. Connectors may run in test or live mode. Test-mode connectors accept only the documented test card numbers.

## Attributes

<table>
  <thead>
    <tr>
      <th>ATTRIBUTE</th>
      <th>DESCRIPTION</th>
      <th>OPTIONS</th>
      <th>DEFAULT</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>action</code></td>
      <td> Optional URL where TeXML requests the next set of instructions after `<Pay>` completes. The request includes normalized `PayResult`, the raw `Result`, and available payment result fields. </td>

      <td />

      <td>-</td>
    </tr>

    <tr>
      <td><code>method</code></td>
      <td> HTTP request type used for the `action` URL. </td>
      <td><code>GET</code>, <code>POST</code></td>
      <td><code>POST</code></td>
    </tr>

    <tr>
      <td><code>statusCallback</code></td>
      <td> Optional URL where Telnyx will send status callbacks for payment progress and completion events. </td>

      <td />

      <td>-</td>
    </tr>

    <tr>
      <td><code>statusCallbackMethod</code></td>
      <td> HTTP request type used for `statusCallback`. </td>
      <td><code>GET</code>, <code>POST</code></td>
      <td><code>POST</code></td>
    </tr>

    <tr>
      <td><code>paymentConnector</code></td>
      <td> The name of the payment connector to use. The connector must be configured in the Telnyx API. Defaults to `Default`. </td>

      <td />

      <td><code>Default</code></td>
    </tr>

    <tr>
      <td><code>chargeAmount</code></td>
      <td> The amount to charge (e.g. `10.50`). Required when `transactionType` is `charge`. Ignored for `tokenize` transactions. </td>

      <td />

      <td>-</td>
    </tr>

    <tr>
      <td><code>currency</code></td>
      <td> The currency for the charge. Pay currently supports `USD`. </td>
      <td><code>USD</code></td>
      <td><code>USD</code></td>
    </tr>

    <tr>
      <td><code>paymentToken</code></td>
      <td> An existing payment token to use for the transaction. If provided, the payment data collection steps are skipped. </td>

      <td />

      <td>-</td>
    </tr>

    <tr>
      <td><code>paymentMethod</code></td>
      <td> The payment method to collect. `credit-card` collects card number, expiration date, postal code, and security code. `ach-debit` collects bank routing and account numbers. </td>
      <td><code>credit-card</code>, <code>ach-debit</code></td>
      <td><code>credit-card</code></td>
    </tr>

    <tr>
      <td><code>transactionType</code></td>
      <td> The transaction type. `charge` processes a payment and returns a `ChargeId`. `tokenize` tokenizes the payment data and returns a `TokenId`. If omitted, Pay infers `tokenize` when `chargeAmount` is absent or zero and `charge` when it is positive. </td>
      <td><code>charge</code>, <code>tokenize</code></td>
      <td>-</td>
    </tr>

    <tr>
      <td><code>description</code></td>
      <td> An optional description for the payment transaction. </td>

      <td />

      <td>-</td>
    </tr>

    <tr>
      <td><code>maxAttempts</code></td>
      <td> The maximum number of attempts for each payment collection step before failing. Valid values are 1 through 3. </td>
      <td><code>1</code> - <code>3</code></td>
      <td><code>1</code></td>
    </tr>

    <tr>
      <td><code>timeout</code></td>
      <td> The timeout in seconds for each DTMF input step. Valid values are 1 through 600. </td>
      <td><code>1</code> - <code>600</code></td>
      <td><code>5</code></td>
    </tr>

    <tr>
      <td><code>interDigitTimeout</code></td>
      <td> The timeout in seconds between consecutive DTMF digits during input. Valid values are 1 through 600. </td>
      <td><code>1</code> - <code>600</code></td>
      <td><code>5</code></td>
    </tr>

    <tr>
      <td><code>voice</code></td>
      <td> The voice used for payment prompts (e.g. `female`, `male`). </td>

      <td />

      <td><code>female</code></td>
    </tr>

    <tr>
      <td><code>language</code></td>
      <td> The language used for payment prompts (e.g. `en-US`, `es-ES`). </td>

      <td />

      <td><code>en-US</code></td>
    </tr>

    <tr>
      <td><code>serviceLevel</code></td>
      <td> The service level for payment processing. </td>
      <td><code>premium</code></td>
      <td><code>premium</code></td>
    </tr>

    <tr>
      <td><code>parameters</code></td>
      <td> A JSON string of additional parameters to pass to the payment connector. </td>

      <td />

      <td>-</td>
    </tr>

    <tr>
      <td><code>prompts</code></td>
      <td> A JSON string of custom prompts for payment collection steps. Can also be specified using nested `<Prompt>` elements. </td>

      <td />

      <td>-</td>
    </tr>

    <tr>
      <td><code>metadata</code></td>
      <td> A JSON string of metadata to attach to the payment transaction. </td>

      <td />

      <td>-</td>
    </tr>
  </tbody>
</table>

## Child verbs/nouns

<table>
  <thead>
    <tr>
      <th>NOUN/VERB</th>
      <th>DESCRIPTION</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>Parameter</code></td>
      <td> Optional key-value parameter merged into the Pay parameters map. Use the `name` and `value` attributes to specify the key and value. </td>
    </tr>

    <tr>
      <td><code>Prompt</code></td>
      <td> Custom text-to-speech prompt for a specific payment collection step. Use the `for` attribute to specify the step and include the prompt text in a nested `<Say>` element. </td>
    </tr>
  </tbody>
</table>

## Connector modes and test cards

Pay connectors can operate in `test` or `live` mode. Before contacting the configured processor, a test-mode connector rejects every card number except those below.

| Card type        | Card number           | Security code     | Expiration date                  |
| ---------------- | --------------------- | ----------------- | -------------------------------- |
| Visa             | `4111 1111 1111 1111` | Any 3 or 4 digits | Any four digits in `MMYY` format |
| Mastercard       | `5555 5555 5555 4444` | Any 3 or 4 digits | Any four digits in `MMYY` format |
| American Express | `3782 822463 10005`   | Any 3 or 4 digits | Any four digits in `MMYY` format |
| Discover         | `6011 1111 1111 1117` | Any 3 or 4 digits | Any four digits in `MMYY` format |
| Diners Club      | `3065 9300 0902 0004` | Any 3 or 4 digits | Any four digits in `MMYY` format |
| JCB              | `3566 0020 2036 0505` | Any 3 or 4 digits | Any four digits in `MMYY` format |
| UnionPay         | `6200 0000 0000 0005` | Any 3 or 4 digits | Any four digits in `MMYY` format |
| Maestro          | `6771 7980 2100 0008` | Any 3 or 4 digits | Any four digits in `MMYY` format |

A test-mode payment using any other card number fails with `ErrorType=invalid-card-number`. Live-mode connectors pass the captured payment details to the configured payment processor.

## Charge a credit card

Collect credit-card details and charge a specific amount. The `paymentConnector` must name a Pay connector configured for the account:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Pay paymentConnector="MyConnector"
         chargeAmount="10.50"
         currency="USD"
         transactionType="charge"
         action="https://example.com/payment-complete"
         statusCallback="https://example.com/pay-status" />
</Response>
```

## Tokenize a credit card

Collect credit-card details and tokenize them without charging:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Pay paymentConnector="MyConnector"
         transactionType="tokenize"
         action="https://example.com/payment-complete"
         statusCallback="https://example.com/pay-status" />
</Response>
```

If `transactionType` is omitted, Pay infers `tokenize` when `chargeAmount` is absent or zero and `charge` when `chargeAmount` is positive.

## Collect ACH bank-account details

Collect a 9-digit bank routing number and a 4–17 digit bank account number:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Pay paymentConnector="MyConnector"
         paymentMethod="ach-debit"
         transactionType="charge"
         chargeAmount="25.00"
         currency="USD"
         action="https://example.com/payment-complete"
         statusCallback="https://example.com/pay-status" />
</Response>
```

## Custom prompts

Override a payment step's text-to-speech prompt with a nested `<Prompt>` and `<Say>`:

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Pay paymentConnector="MyConnector"
         transactionType="charge"
         chargeAmount="10.50"
         action="https://example.com/payment-complete">
        <Prompt for="payment-card-number">
            <Say>Please enter your credit card number.</Say>
        </Prompt>
        <Prompt for="security-code">
            <Say>Please enter the security code from your card.</Say>
        </Prompt>
    </Pay>
</Response>
```

The supported `for` values are `payment-card-number`, `expiration-date`, `postal-code`, `security-code`, `bank-routing-number`, and `bank-account-number`.

Prompts may be qualified by `attempt`, `errorType`, and `cardType`. Qualifiers are optional and may be combined. `attempt` accepts a space-separated list of 1-based attempt numbers. Card-type values are lowercase and case-sensitive.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Pay paymentConnector="MyConnector"
         transactionType="charge"
         chargeAmount="10.50"
         maxAttempts="3">
        <Prompt for="security-code" cardType="amex">
            <Say>Please enter the 4-digit security code from the front of your card.</Say>
        </Prompt>
        <Prompt for="security-code">
            <Say>Please enter the security code from your card.</Say>
        </Prompt>
        <Prompt for="payment-card-number" attempt="2 3" errorType="invalid-card-number">
            <Say>That card number was not accepted. Please try again.</Say>
        </Prompt>
    </Pay>
</Response>
```

The `prompts` JSON attribute is an alternative to nested `<Prompt>` elements. Each step may contain a string or a list of prompt objects:

```xml theme={null}
<Response>
    <Pay paymentConnector="MyConnector"
         transactionType="tokenize"
         prompts='{"payment-card-number":[{"text":"Enter your card number."},{"text":"Please try again.","attempt":"2 3"}]}' />
</Response>
```

## Additional connector parameters

Pass extra string parameters with nested `<Parameter>` elements. Child parameters override keys with the same name in the `parameters` JSON attribute.

```xml theme={null}
<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Pay paymentConnector="MyConnector"
         transactionType="charge"
         chargeAmount="10.50"
         parameters='{"source":"phone"}'>
        <Parameter name="order_id" value="ORD-12345" />
        <Parameter name="customer_id" value="CUST-67890" />
    </Pay>
</Response>
```

## Status callbacks

When `statusCallback` is set, TeXML sends callbacks as payment collection progresses and another callback when the Pay session completes. Parameters are form encoded for `POST` callbacks and query encoded for `GET` callbacks.

The following call and payment context fields are included when available:

| Parameter          | Description                                                                                                                                                                       |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AccountSid`       | ID of the Telnyx account that owns the call.                                                                                                                                      |
| `CallSid`          | Call Control ID of the call leg running Pay.                                                                                                                                      |
| `CallSidLegacy`    | The same Call Control ID, provided for compatibility.                                                                                                                             |
| `CallSessionId`    | ID shared by call legs in the same call session.                                                                                                                                  |
| `ConnectionId`     | ID of the Call Control or TeXML connection.                                                                                                                                       |
| `PaymentMethod`    | Payment method: `credit-card` or `ach-debit`.                                                                                                                                     |
| `PaymentConnector` | Name of the Pay connector used for the transaction.                                                                                                                               |
| `For`              | Current collection step, such as `payment-card-number`, `expiration-date`, `postal-code`, `security-code`, `bank-routing-number`, `bank-account-number`, or `payment-processing`. |

### Progress callback

A progress callback always contains `Status=processing` and `Result=pending`. It can also contain:

| Parameter      | Description                                                                                                                                                                                                                  |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Attempt`      | Current 1-based attempt number for the step.                                                                                                                                                                                 |
| `ErrorType`    | Step-level error, such as `timeout`, `invalid-card-number`, `invalid-date`, `invalid-security-code`, `invalid-postal-code`, `invalid-bank-routing-number`, or `invalid-bank-account-number`. Omitted when the step succeeds. |
| `PaymentError` | Processor-level error description, when available.                                                                                                                                                                           |

Progress callbacks accumulate the masked payment data collected so far. For example, the expiration-date callback can include the card number and card type collected by an earlier step.

### Completed callback

The final status callback contains `Status=completed` and a normalized `Result` of `success` or `failed`. It can also contain:

| Parameter      | Description                                                                |
| -------------- | -------------------------------------------------------------------------- |
| `ChargeId`     | Charge identifier returned for a successful `charge` transaction.          |
| `TokenId`      | Token identifier returned for a successful `tokenize` transaction.         |
| `ErrorType`    | Step-level error that caused the Pay session to fail, when available.      |
| `PaymentError` | Processor-level error description, when available.                         |
| `PayErrorCode` | Error code returned by the payment connector or processor, when available. |
| `Attempt`      | Last reported attempt number, when available.                              |

### Masked payment-data fields

Progress and completed callbacks include these fields when the corresponding values have been collected:

| Parameter               | Description                                                                                              |
| ----------------------- | -------------------------------------------------------------------------------------------------------- |
| `PaymentCardNumber`     | Masked card number with only the last four digits visible.                                               |
| `PaymentCardType`       | Detected lowercase card type, such as `visa`, `mastercard`, `amex`, `discover`, `diners-club`, or `jcb`. |
| `ExpirationDate`        | Expiration date in `MMYY` format.                                                                        |
| `SecurityCode`          | Fully masked security code.                                                                              |
| `PaymentCardPostalCode` | Billing postal code.                                                                                     |
| `BankAccountNumber`     | Masked bank account number with only the last two digits visible.                                        |
| `BankRoutingNumber`     | Bank routing number.                                                                                     |
| `BankAccountType`       | Bank account type when supplied by the processor.                                                        |

## Action request

After Pay completes, TeXML requests the `action` URL using `method`. If `action` is omitted, TeXML requests the current document URL instead. The response must contain the next TeXML instructions.

The action request has its own payload shape; it is not identical to the completed `statusCallback` payload.

| Parameter                 | Description                                                                                                                                     |
| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `PayResult`               | Normalized result: `success` or `failed`.                                                                                                       |
| `Result`                  | Raw Pay result, such as `success`, `validation-error`, `payment-connector-error`, `internal-error`, `too-many-failed-attempts`, or `cancelled`. |
| `CallSessionId`           | Call session ID, when available.                                                                                                                |
| `PaymentMethod`           | Payment method: `credit-card` or `ach-debit`.                                                                                                   |
| `PaymentConnector`        | Name of the Pay connector used.                                                                                                                 |
| `PaymentStep`             | Last payment step, when available.                                                                                                              |
| `ErrorCode`               | Step-level error from the Pay result, when available.                                                                                           |
| `PaymentError`            | Processor-level error description, when available.                                                                                              |
| `PayErrorCode`            | Connector or processor error code, when available.                                                                                              |
| `ChargeId`                | Charge identifier for a successful `charge` transaction.                                                                                        |
| `PaymentConfirmationCode` | Alias of `ChargeId`.                                                                                                                            |
| `TokenId`                 | Token identifier for a successful `tokenize` transaction.                                                                                       |
| `PaymentToken`            | Alias of `TokenId`.                                                                                                                             |

The action request also includes any available masked payment-data fields listed above.