Voice

Pay

View as Markdown

Overview

The <Pay> verb enables secure payment processing during voice calls. When implemented in your voice application, it handles the complete payment flow including data collection, validation, and processing through your configured payment gateway.

The <Pay> verb also has two nouns that are embedded within it:

  • <Parameter>: Pass custom parameters to your payment processor.
  • <Prompt>: Customize the prompts used during payment collection.

Core functionality

  • Secure payment information collection
  • Real-time payment processing
  • Payment method tokenization
  • Multi-currency support
  • Automated retry handling
  • Status tracking via webhooks

Transaction types

The <Pay> verb supports two primary transaction types: immediate charges and tokenization.

Immediate charges

When you need to process a payment right away, use an immediate charge transaction. This collects the payment details and processes the transaction in one step.

To execute an immediate charge:

1<Pay chargeAmount="25.00"/>

Setting any positive value for chargeAmount initiates an immediate charge transaction.

Tokenization

Tokenization allows you to securely store payment information for future use. Instead of processing a payment, it generates a secure token that represents the payment method. This is particularly useful for:

  • Subscription services
  • Recurring billing

To tokenize payment information:

1<Pay chargeAmount="0"/>

You can also omit the chargeAmount attribute entirely:

The actual token is provided & stored by your payment processor, which can be used for future transactions without requiring customers

to re-enter their payment details. This may differ depending on the payment processor you are using.

Attributes

minPostalCodeLength
integerRequired

Minimum required length for postal code input. Used for input validation.

paymentConnectorUrl
stringRequired

The URL to which to POST the encrypted payment data.

securityCode
booleanDefaults to trueRequired

Controls whether CVV/security code collection is required. When false, skips security code collection.

action
string

HTTPS endpoint that receives POST requests after payment completion. Must be HTTPS. Response determines next cXML instructions. For tokenization, receives PaymentToken and ProfileId. For charges, receives PaymentConfirmationCode. Defaults to the current cXML document URL.

chargeAmount
decimal

Amount to charge. Set to 0 or omit for tokenization only. Must be between 0 and 1,000,000.

currency
stringDefaults to usd

Three-letter currency code (e.g., usd, eur, gbp). Must be supported by selected payment connector. Currently only usd is accepted.

description
string

Transaction description passed to payment processor. Appears in transaction records.

input
stringDefaults to dtmf

The only supported input method for payment data collection. All captured digits are automatically redacted in logs.

language
stringDefaults to en-us

Controls prompt language. Supports en-AU, en-CA, en-GB, en-IN, en-US for all payments. Additional es-ES, es-MX, fr-CA, fr-FR, de-DE, it-IT for credit card only. See language list.

maxAttempts
integerDefaults to 1

Maximum number of retry attempts when timeout occurs or invalid data is received. Allowed values are 1, 2, or 3. Payment flow terminates after maxAttempts is reached.

paymentMethod
stringDefaults to credit-card

Determines payment collection flow. Credit card flow captures card number, expiration, security code, and postal code. ACH flow captures routing and account numbers.

postalCode
string | booleanDefaults to true

Controls postal code collection. When false, skips collection for postal code. When true, prompts the user for collection. When a String value, uses provided value without needing to collect the postal code from the user.

statusCallback
string

HTTPS endpoint that receives real-time payment status updates via POST requests. Includes details about current payment stage, errors, and attempt counts. See Status Callback Parameters for more details.

timeout
integerDefaults to 5

Number of seconds to wait for the next digit input before timing out. Must be a positive integer greater than 3 seconds. Applies to all input collection stages.

tokenType
stringDefaults to reusable

Determines token persistence. Allowed values are one-time or reusable. One-time for single use, reusable for recurring use. Payment-method specific to certain processors.

validCardTypes
stringDefaults to visa mastercard amex

Space-separated list of accepted card types. Validates card number against specified types. Allowed values: visa, mastercard, amex, maestro, discover, optima, jcb, diners-club, enroute.

Webhook request parameters

paymentConnectorUrl request parameters

When a transaction is completed, SignalWire will POST to your paymentConnectorUrl URL. Based on the transaction type, the body of the request will contain the below parameters:

Response from paymentConnectorUrl

A valid response from your paymentConnectorUrl must be provided to indicate the success or failure of the transaction. More information can be found in the Webhook Response section.

cardnumber
string

Customer’s credit card number.

chargeAmount
decimal

Amount to charge.

currency_code
string

Three-letter currency code.

cvv
string

Card security code.

description
string

Transaction description.

expiry_month
string

Card expiration month (2 digits).

expiry_year
string

Card expiration year (2 digits).

method
string

Payment method (credit-card).

parameters
object

Custom key-value parameters.

postal_code
string

Billing postal code.

transaction_id
string

Unique identifier for the transaction.

Example

1{
2  "transaction_id":"id",
3  "method":"credit-card",
4  "cardnumber":"1234123412341234",
5  "cvv":"123",
6  "postal_code":"12345",
7  "description":"renew plan",
8  "chargeAmount":123.45,
9  "expiry_month":"01",
10  "expiry_year":"38",
11  "currency_code":"USD",
12  "parameters":{
13    "custom1":"value1"
14  }
15}

action request parameters

When a transaction is completed, SignalWire will POST to your action URL. The body of the request will contain the standard request parameters as well as the following parameters:

Response from action URL

A valid cXML response must be provided if the action URL is provided. More information can be found in the Webhook Response section.

BankAccountNumber
string

Masked bank account number.

BankRoutingNumber
string

Bank routing number.

ConnectorError
string

Raw processor error details.

ExpirationDate
string

Card expiration in MMYY format.

PayErrorCode
string

Numeric error reference.

PaymentCardNumber
string

Masked card number (last 4 digits visible).

PaymentCardPostalCode
string

Postal code provided.

PaymentCardType
string

Card brand (visa, mastercard, etc.).

PaymentConfirmationCode
string

Transaction confirmation code.

PaymentError
string

Detailed error information.

PaymentMethod
string

Type of payment method used.

PaymentToken
string

Tokenized payment method reference.

ProfileId
string

Customer profile identifier from payment processor.

Result
string

Final outcome of the payment attempt. The possible values can be seen in the Result Values table.

SecurityCode
string

Masked security code.

Result values

ValueDescription
successPayment processed successfully
too-many-failed-attemptsMaximum retry attempts reached
payment-connector-errorGateway communication failure
caller-interrupted-with-starUser canceled with * key
caller-hung-upCall terminated by user
validation-errorInvalid parameter provided
internal-errorSystem processing error

statusCallback request parameters

When a status change occurs, the following parameters are sent to your statusCallback URL:

Attempt
integer

Current attempt number.

ErrorType
string

Specifies the nature of the error encountered (if any). Refer to the table below for detailed error type descriptions. The possible values can be seen in the Error Types table.

ExpirationDate
string

Card expiration date.

For
string

Indicates the present phase of the <Pay> request. The table below outlines the potential values. Possible values can be seen in the For Values table.

PaymentCardNumber
string

Masked card number.

PaymentCardPostalCode
string

Postal code provided.

PaymentCardType
string

Type of card provided.

PaymentMethod
string

Type of payment being processed.

SecurityCode
string

Masked security code.

Status callback events

EventDescription
payment-card-numberCollecting card number
expiration-dateCollecting expiration date
security-codeCollecting CVV/security code
postal-codeCollecting postal code
bank-routing-numberCollecting routing number
bank-account-numberCollecting account number
payment-processingProcessing transaction

For values

ValueDescription
payment-card-numberRequesting the customer’s credit or debit card details
expiration-dateRequesting the expiration date of the customer’s payment card
security-codeRequesting the security code (CVV) of the customer’s payment card
postal-codeRequesting the postal code linked to the customer’s payment card
payment-processingExecuting the payment transaction

Error types

ErrorDescription
input-timeoutUser input timeout
invalid-card-numberFailed card validation
invalid-card-typeUnsupported card type
invalid-dateInvalid expiration date
invalid-security-codeInvalid CVV format
invalid-postal-codeInvalid postal code format
invalid-bank-routing-numberInvalid routing number
invalid-bank-account-numberInvalid account number
session-in-progressConcurrent session attempt

Webhook response

paymentConnectorUrl response

The response from your paymentConnectorUrl is used to inform if the transaction was successful or not.

Successful transaction

When a transaction is successful, the webhook should respond with one of the following formats (depending on the transaction type):

1{
2  "charge_id":"charge_id",
3  "error_code":null,
4  "error_message":null
5}

Unsuccessful transaction

When a transaction is unsuccessful (declined by the payment processor), the webhook should respond with the following format:

1{
2  "charge_id": null,
3  "error_code": "some error code",
4  "error_message": "some error message"
5}

action response

When a transaction is completed, SignalWire will POST to your action URL. The response should return valid cXML for the next step in your application.

Example

1<Response>
2  <Say>Thank you for your payment. Your transaction has been completed.</Say>
3  <Hangup/>
4</Response>

Language support

The language attribute controls the language of automated prompts during payment collection.

You can customize prompt messages in any language using the <Prompt> noun, regardless of the selected language attribute.

Credit card payments

All credit card payments support the following languages:

English variants

  • en-AU (Australian English)
  • en-CA (Canadian English)
  • en-GB (British English)
  • en-IN (Indian English)
  • en-US (American English)

Additional languages

  • es-ES (European Spanish)
  • es-MX (Mexican Spanish)
  • fr-CA (Canadian French)
  • fr-FR (European French)
  • de-DE (German)
  • it-IT (Italian)

Examples

Simple payment collection:

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Say>Please enter your payment information</Say>
4    <Pay chargeAmount="20.45"/>
5</Response>

Payment with status tracking:

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Say>Please enter your payment information</Say>
4    <Pay 
5        chargeAmount="20.45"
6        action="https://your-callback-url.example.com/pay"
7        statusCallback="https://your-callback-url.example.com/status"
8    />
9</Response>

Basic tokenization:

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Say>Please enter your card information to save for future use</Say>
4    <Pay 
5        tokenType="reusable"
6        chargeAmount="0"
7    />
8</Response>

Tokenization with validation:

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Say>Please enter your card information</Say>
4    <Pay 
5        tokenType="reusable"
6        chargeAmount="0"
7        validCardTypes="visa mastercard"
8        securityCode="true"
9        postalCode="true"
10    />
11</Response>

Custom retry logic:

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Say>Please enter your payment information</Say>
4    <Pay 
5        chargeAmount="75.00"
6        maxAttempts="3"
7        timeout="10"
8    />
9</Response>

International payment:

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3    <Say>Por favor, ingrese su información de pago</Say>
4    <Pay 
5        chargeAmount="100.00"
6        currency="mxn"
7        language="es-MX"
8        description="Mexican peso transaction"
9    />
10</Response>

Example with custom parameters and prompts

1<Response>
2<Pay chargeAmount="123.45" paymentConnectorUrl="https://example.com/accept-payment" description="renew plan">
3  <Parameter name="custom1" value="value1"/>
4  <Prompt name="payment-card-number" attempt="1"><Say>Let's collect your payment information. Please enter your credit card number</Say></Prompt>
5  <Prompt name="payment-card-number" attempt="2 3"><Say>Please enter your credit card number</Say></Prompt>
6  <Prompt for="security-code" cardType="amex"><Say>Please enter your credit card’s security code. It's the 4 digits located on the front of your card. </Say></Prompt>
7</Pay>
8</Pay>
9</Response>

Security best practices

  1. Always use HTTPS for callback URLs
  2. Implement webhook validation
  3. Monitor payment status callbacks
  4. Handle errors gracefully
  5. Store tokens securely
  6. Use appropriate timeout values
  7. Implement proper error handling
  8. Validate all inputs
  9. Monitor transaction patterns
  10. Keep payment connector configurations secure