pay

Enable secure payment processing during voice calls. When implemented in your voice application, it manages the entire payment flow, including data collection, validation, and processing, through your configured payment gateway.

Transaction Types

The pay method supports two primary transaction types: charges and tokenization.

Charges

When you need to process a payment right away, use a charge transaction. This collects the payment details and processes the transaction in real-time.

1 version: 1.0.0
2 sections:
3   main:
4     - pay:
5         charge_amount: 25.00
6         payment_connector_url: "https://example.com/process"

Setting any positive value for charge_amount initiates a charge transaction.

Tokenization

Tokenization allows you to securely store payment information for future use. Instead of processing a payment immediately, it generates a secure token that represents the payment method. To initiate a tokenization transaction, either pass charge_amount as 0 or omit the charge_amount attribute entirely.

The token is provided and stored by your payment processor and can be used for future transactions without requiring customers to re-enter their payment details. Note that this behavior may vary depending on the payment processor you are using.

1 version: 1.0.0
2 sections:
3   main:
4     - pay:
5         charge_amount: 0
6         payment_connector_url: "https://example.com/process"

Properties

objectRequired

An object that accepts the following properties.

pay.payment_connector_url

stringRequired

The URL to make POST requests with all the gathered payment details. This URL processes the final payment transaction and returns the results in the response. See payment_connector_url details below.

pay.charge_amount

string

The amount to charge against payment method passed in the request. Float value with no currency prefix passed as string.

pay.currency

stringDefaults to usd

Uses the ISO 4217 currency code of the charge amount.

pay.description

string

Custom description of the payment provided in the request.

pay.input

stringDefaults to dtmf

The method of how to collect the payment details. Currently only dtmf mode is supported.

pay.language

stringDefaults to en-US

Language to use for prompts being played to the caller by the pay method. Supported languages are listed in the Voice and Languages page.

pay.max_attempts

integerDefaults to 1

Number of times the pay method will retry to collect payment details.

pay.min_postal_code_length

integerDefaults to 0

The minimum length of the postal code the user must enter.

pay.parameters

object[]

Array of parameter objects to pass to your payment processor. Enables you to pass custom parameters or include additional payment details not covered by the standard pay attributes.

parameters[].name

stringRequired

The identifier for your custom parameter. This will be the key in the parameters object.

parameters[].value

stringRequired

The value associated with the parameter. This will be the value in the parameters object.

pay.payment_method

string

Indicates the payment method which is going to be used in this payment request. Currently only credit-card is supported.

pay.postal_code

boolean|stringDefaults to true

Takes true, false or real postcode (if it’s known beforehand) to let pay method know whether to prompt for postal code.

pay.prompts

object[]

Array of prompt objects for customizing the audio prompts played during different stages of the payment process. If no custom prompts are provided, default prompts will be used. If custom prompts are provided but certain payment steps are omitted, the system will fall back to the default prompts for those steps.

prompts[].for

stringRequired

The payment step this prompt is for. Possible values:

payment-card-number - Collect the payment card number. Default: “Please enter your credit card number”
expiration-date - Collect the expiration date. Default: “Please enter your credit card’s expiration date. 2 digits for the month and 2 digits for the year”
security-code - Collect the security code. Default: “Please enter your credit card’s security code. It’s the 3 digits located on the back of your card”
postal-code - Collect the postal code. Default: “Please enter your billing postal code”
payment-processing - Played during payment processing. Default: “Payment processing. Please wait”
payment-completed - Played when payment succeeds. Default: “Payment completed. Thank you”
payment-failed - Played when payment fails. Default: “Payment failed”
payment-canceled - Played when payment is cancelled. Default: “Payment canceled”

prompts[].actions

object[]Required

Array of action objects to execute for this prompt. Each action can either play an audio file or speak a phrase using text-to-speech.

actions[].type

stringRequired

The action to perform. Allowed values: Say (text-to-speech), Play (play an audio file).

actions[].phrase

stringRequired

When type is Say, the text to be spoken. When type is Play, the URL to the audio file.

prompts[].attempts

string

Which payment attempt(s) this prompt applies to. The value increments when a payment fails. Use a single number (e.g., "1") or space-separated numbers (e.g., "2 3") to target specific attempts.

prompts[].card_type

string

Space-separated list of card types this prompt applies to. Allowed values: visa, mastercard, amex, maestro, discover, optima, jcb, diners-club.

prompts[].error_type

string

Space-separated list of error types this prompt applies to. Possible values:

timeout - User input timeout
invalid-card-number - Failed card validation
invalid-card-type - Unsupported card type
invalid-date - Invalid expiration date
invalid-security-code - Invalid CVV format
invalid-postal-code - Invalid postal code format
session-in-progress - Concurrent session attempt
invalid-bank-routing-number - Invalid bank routing number
invalid-bank-account-number - Invalid bank account number
input-matching-failed - Input matching failed
card-declined - Payment declined

pay.security_code

booleanDefaults to true

Takes true or false to let pay method know whether to prompt for security code.

pay.status_url

string

The URL to send requests for each status change during the payment process. See the status_url request body section for more details.

pay.timeout

integerDefaults to 5

Limit in seconds that pay method waits for the caller to press another digit before moving on to validate the digits captured.

pay.token_type

stringDefaults to reusable

Whether the payment is a one off payment or re-occurring. Allowed values: one-time, reusable.

pay.valid_card_types

stringDefaults to visa mastercard amex

List of payment cards allowed to use in the requested payment process, separated by a space. Allowed values: visa, mastercard, amex, maestro, discover, jcb, diners-club.

pay.voice

stringDefaults to woman

Text-to-speech voice to use. Supported voices are listed in the Voice and Languages page.

`status_url` request body

The status_url parameter is used to send requests for each status change during the payment process.

event_type

string

The type of event that is being reported. Will always be calling.call.pay.

event_channel

string

The channel that the event is being reported from.

timestamp

number

The timestamp of the event in the format of unix timestamp.

project_id

string

The project ID the event is being reported from.

space_id

string

The Space ID the event is being reported from.

params

object

An object containing the parameters of the event.

params.status_url

string

The URL to send requests to for each status change during the payment process.

params.status_url_method

string

The method to use for the requests to the status_url.

params.for

string

The status of the payment process.

params.error_type

string

The error type of the payment process.

params.payment_method

string

The payment method of the payment process.

params.payment_card_number

string

The payment card number of the payment process.

params.payment_card_type

string

The payment card type of the payment process.

params.security_code

string

The security code of the payment process.

params.expiration_date

string

The expiration date of the payment process.

params.payment_card_postal_code

string

The payment card postal code of the payment process.

params.control_id

string

The control ID of the payment process.

params.call_id

string

The call ID of the payment process.

params.node_id

string

The node ID of the payment process.

Request format

Below is an example of the request body that will be sent to the status_url.

1 {
2   "event_type": "calling.call.pay",
3   "event_channel": "swml:XXXX-XXXX-XXXX-XXXX-XXXX",
4   "timestamp": 1743707517.12267,
5   "project_id": "XXXX-XXXX-XXXX-XXXX-XXXX", 
6   "space_id": "XXXX-XXXX-XXXX-XXXX-XXXX",
7   "params": {
8     "status_url": "https://example.com/status",
9     "status_url_method": "POST",
10     "for": "payment-completed",
11     "error_type": "",
12     "payment_method": "credit-card",
13     "payment_card_number": "************1234",
14     "payment_card_type": "visa",
15     "security_code": "***",
16     "expiration_date": "1225",
17     "payment_card_postal_code": "23112",
18     "control_id": "XXXX-XXXX-XXXX-XXXX-XXXX",
19     "call_id": "XXXX-XXXX-XXXX-XXXX-XXXX",
20     "node_id": "XXXX-XXXX-XXXX-XXXX-XXXX"
21   }
22 }

`payment_connector_url`

SignalWire sends a POST request to the payment_connector_url once all required payment information has been collected from the caller. Your endpoint processes the payment and returns the result.

Request body

transaction_id

string

Unique identifier for the transaction.

method

string

The payment method (e.g., credit-card).

cardnumber

string

The card number collected from the caller.

cvv

string

The card security code.

expiry_month

string

The card expiry month (e.g., 12).

expiry_year

string

The card expiry year (e.g., 99).

postal_code

string

The billing postal code.

chargeAmount

string

The amount to charge.

currency_code

string

The ISO 4217 currency code.

token_type

string

The token type (one-time or reusable).

description

string

The payment description provided in the pay method.

Request example

1 {
2   "transaction_id": "8c9d14d5-52ae-4e2e-b880-a14e6e1cda7d",
3   "method": "credit-card",
4   "cardnumber": "************1234",
5   "cvv": "***",
6   "postal_code": "123456",
7   "description": "Payment description",
8   "chargeAmount": "10.55",
9   "token_type": "reusable",
10   "expiry_month": "12",
11   "expiry_year": "99",
12   "currency_code": "usd"
13 }

Response format

Your endpoint must respond with JSON. The format varies depending on the transaction type.

Successful charge

Successful tokenization

Failed charge

Failed tokenization

Return a 200 HTTP status code with:

charge_id

string

A unique identifier for the successful transaction.

error_code

null

Must be null for successful transactions.

error_message

null

Must be null for successful transactions.

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

Error responses will trigger the payment-failed prompt in your SWML application.

Variables

When the payment process completes, the following variables are set in the vars scope. Access them in subsequent SWML instructions using the ${variable} syntax (e.g., ${pay_result}).

pay_result

string

The overall outcome of the payment process. Possible values:

success - The payment was successful.
too-many-failed-attempts - The caller exceeded the max_attempts limit.
payment-connector-error - The payment connector returned an error.
caller-interrupted-with-star - The caller pressed the * key to cancel.
relay-pay-stop - The payment was stopped via the STOP command.
caller-hung-up - The caller hung up before completing payment.
validation-error - Card details failed validation.
internal-error - An internal system error occurred.

pay_payment_results

object

Detailed payment results returned by the payment processor, including card details, tokens, and any error information. Access nested properties with dot notation (e.g., ${pay_payment_results.payment_token}).

pay_payment_results.payment_token

string

Token generated by the payment processor. Use this for future transactions when using tokenization (charge_amount: 0).

pay_payment_results.payment_confirmation_code

string

Confirmation code returned by the payment processor for a successful charge.

pay_payment_results.payment_card_number

string

Redacted card number (e.g., ************1234).

pay_payment_results.payment_card_type

string

Type of card used (e.g., visa, mastercard, amex).

pay_payment_results.payment_card_expiration_date

string

Card expiration date (e.g., 1225 for December 2025).

pay_payment_results.payment_card_security_code

string

Redacted security code (e.g., ***).

pay_payment_results.payment_card_postal_code

string

Postal code entered by the caller.

pay_payment_results.payment_error

string

Error description if the payment failed. Empty on success.

pay_payment_results.payment_error_code

string

Error code if the payment failed. Empty on success.

pay_payment_results.connector_error

object

Error object from the payment connector. Only present when the connector returns an error.

connector_error.code

string

Connector-specific error code.

connector_error.message

string

Connector-specific error message.

Examples

Simple payment collection

1 version: 1.0.0
2 sections:
3   main:
4     - pay:
5         charge_amount: '20.45'
6         payment_connector_url: "https://example.com/process"
7         status_url: "https://example.com/status"

Basic tokenization

1 version: 1.0.0
2 sections:
3   main:
4     - pay:
5         token_type: "reusable"
6         charge_amount: '0'
7         payment_connector_url: "https://example.com/tokenize"

Retry logic

1 version: 1.0.0
2 sections:
3   main:
4     - pay:
5         charge_amount: '75.00'
6         payment_connector_url: "https://example.com/process"
7         max_attempts: 3
8         timeout: 10

Custom parameters

1 version: 1.0.0
2 sections:
3   main:
4     - pay:
5         charge_amount: "10.00"
6         payment_connector_url: "https://example.com/process"
7         parameters:
8           - name: "my_custom_parameter_1"
9             value: "my_custom_value_1"

International payment with custom prompts

1 version: 1.0.0
2 sections:
3   main:
4     - pay:
5         charge_amount: '100.00'
6         payment_connector_url: "https://example.com/process"
7         currency: "pln"
8         language: "pl-PL"
9         description: "Polish zloty transaction"
10         prompts:
11           - for: "payment-card-number"
12             actions:
13               - type: "Say"
14                 phrase: "Witamy w telefonicznym systemie płatności"
15               - type: "Say"
16                 phrase: "Proszę wprowadzić numer karty płatniczej"
17           - for: "payment-card-number"
18             error_type: "invalid-card-number timeout invalid-card-type"
19             actions:
20               - type: "Say"
21                 phrase: "Wprowadziłeś błędny numer karty płatniczej. Proszę spróbować ponownie"
22           - for: "payment-completed"
23             actions:
24               - type: "Say"
25                 phrase: "Płatność zakończona powodzeniem"

Handling payment results

1 version: 1.0.0
2 sections:
3   main:
4     - answer: {}
5     - pay:
6         charge_amount: '25.00'
7         payment_connector_url: "https://example.com/process"
8     - cond:
9         - when: "pay_result == 'success'"
10           then:
11             - play:
12                 url: 'say: Payment successful. Your confirmation code is ${pay_payment_results.payment_confirmation_code}.'
13         - else:
14             - play:
15                 url: 'say: Payment was not completed. Please try again later.'