pay
Enable secure payment processing during voice calls.
When implemented in your voice application, it manages the entire payment flow —
collecting card details (or bank account details, with payment_method: ach-debit) from the caller via DTMF, then POSTing them to a payment_connector_url you host.
Your server is responsible for charging the payment method through your payment processor (Stripe, Braintree, etc.) and returning the result to SignalWire.
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.
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.
Your payment connector returns the stored payment method’s identifier as token_id. See Response format.
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.
Properties
pay
An object that accepts the following properties.
pay.payment_connector_url
The URL to make POST requests with all the gathered payment details. Must be an HTTPS URL, or a SWML variable that resolves to one. This URL processes the final payment transaction and returns the results in the response. See payment_connector_url details below.
pay.charge_amount
The amount to charge against payment method passed in the request. Float value with no currency prefix passed as string. When omitted, 0.00 is sent to your payment connector.
pay.currency
Uses the ISO 4217 currency code of the charge amount.
pay.description
Custom description of the payment provided in the request.
pay.input
The method of how to collect the payment details. Currently only dtmf mode is supported.
While entering a value (card number, expiration date, security code, or postal code), the caller can press # to submit the entry immediately instead of waiting for the timeout. Pressing * cancels the payment, and pay_result becomes caller-interrupted-with-star.
pay.language
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
Number of attempts the caller gets to enter each payment detail, such as the card number or expiration date.
Each detail is counted separately.
Set a value from 1 to 3. Values outside that range are ignored, and the default 1 is used instead.
With the default 1, the caller gets no retry after a failed entry.
pay.min_postal_code_length
The minimum length of the postal code the user must enter.
pay.parameters
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.
See the payment connector request body for how they’re sent.
parameters[].name
The identifier for your custom parameter. In the payment_connector_url request, each parameter becomes a single-key object with this name as its key.
parameters[].value
The value associated with the parameter. In the payment_connector_url request, this is the value of the parameter’s single-key object.
pay.payment_method
The payment method to collect from the caller. Allowed values:
credit-card- Collect a card number, expiration date, and (by default) security code and postal code.ach-debit- Collect a bank routing number and bank account number.
Whether your payment processor accepts a given method is up to your payment connector.
pay.bank_account_type
The bank account type sent to your payment connector. Applies when payment_method is ach-debit.
Allowed values: consumer-checking, consumer-savings, commercial-checking.
pay.postal_code
Whether to prompt for the postal code, or the postal code itself. Applies to card payments.
Pass a quoted string, such as "true": an unquoted YAML or JSON boolean is rejected.
- The values that turn
security_codeon, such as"true", prompt the caller. "false","f","no","off","disabled","inactive", and"disallow"(in any case), and numbers equal to zero, such as"0", skip the prompt.- Any other value, such as
"K1A 0B1", is taken as the postal code: the caller isn’t prompted, and that value is sent to your payment connector.
A postal code made only of digits is read as a number, so "94107" prompts the caller as "true" does, and the value isn’t sent.
pay.prompts
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
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”bank-routing-number- Collect the bank routing number. Default: “Please enter your bank routing number. It’s the 9 digits at the bottom left of your check”bank-account-number- Collect the bank account number. Default: “Please enter your bank account number, then press pound”payment-processing- Played during payment processing. Default: “Payment processing. Please wait”payment-completed- Played when your payment connector responds with HTTP200. Checkpay_resultfor the final outcome. Default: “Payment completed. Thank you”payment-failed- Played when collecting payment details fails, or when your payment connector responds with a status other than200. Default: “Payment failed”payment-canceled- Played when payment is cancelled. Default: “Payment canceled”
prompts[].actions
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.
Ignored when play is set.
A prompt with neither play nor a non-empty actions array doesn’t replace the default prompt.
actions[].type
The action to perform. Allowed values: Say (text-to-speech), Play (play an audio file).
actions[].phrase
When type is Say, the text to be spoken. When type is Play, the URL to the audio file.
prompts[].play
Array of media items to play for this prompt: audio files, text-to-speech, silence, or ringtones.
When play is present, even as an empty array, it takes precedence and actions is ignored.
play[].type
The type of media to play. Allowed values: audio, tts, silence, ringtone.
play[].params
Parameters for the media item. Which properties apply depends on type.
params.url
Required when type is audio. HTTP or HTTPS URL of the audio file to play.
params.text
Required when type is tts. The text to speak.
params.language
Used when type is tts. Language code for the speech, such as en-US. Falls back to the pay method’s language.
params.gender
Used when type is tts. Voice gender, used when no voice is set here or on the pay method. Allowed values: male, female. Defaults to female.
params.voice
Used when type is tts. Text-to-speech voice. Falls back to the pay method’s voice.
params.duration
Required when type is silence, optional when type is ringtone. Duration in seconds; must be a positive number.
For ringtone, the maximum ringtone duration.
params.name
Required when type is ringtone. The ringtone to play: a two-letter country code that selects that country’s ringtone cadence, or bong.
Allowed values: au, be, ca, cn, cy, cz, de, dk, dz, eg, es, fi, fr, hu, il, in, jp, ko, pk, pl, ro, rs, ru, sa, tr, uk, us, at, bg, br, ch, cl, ee, gr, it, lt, mx, my, nl, no, nz, ph, pt, se, sg, th, za, tw, ve, bong.
prompts[].attempt
Space-separated list of the attempts (1, 2, or 3) this prompt applies to, such as "1" or "2 3".
Attempts count per payment detail being collected, not per payment: each detail starts again at attempt 1.
prompts[].card_type
Space-separated list of card types this prompt applies to.
Allowed values: visa, mastercard, amex, maestro, discover, jcb, diners-club.
Unrecognized values are ignored; if no value is recognized, the prompt applies to every card type.
prompts[].error_type
Space-separated list of error types this prompt applies to. Possible values:
timeout- User input timeoutinvalid-card-number- Failed card validationinvalid-card-type- Unsupported card typeinvalid-date- Invalid expiration dateinvalid-security-code- Invalid CVV formatinvalid-postal-code- Invalid postal code formatinvalid-bank-routing-number- Invalid bank routing numberinvalid-bank-account-number- Invalid bank account numberinput-matching-failed- Input matching failed. Accepted, butpaydoesn’t currently report this errorcard-declined- Payment declinedbank-account-declined- Bank account payment declinedinvalid-bank-account-type- Unsupported bank account type
pay.say_voice
Alternative name for voice. Used only when voice is not set.
pay.security_code
Whether to prompt for the card security code. Applies to card payments.
Pass a quoted string, such as "true": an unquoted YAML or JSON boolean is rejected.
"true", "t", "yes", "on", "enabled", "active", and "allow" (in any case), and non-zero whole numbers, such as "1", turn the prompt on.
Any other value turns it off.
pay.status_url
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
Limit in seconds that pay method waits for the caller to press another digit before moving on to validate the digits captured. The caller can press # to finish an entry immediately rather than waiting for this timeout.
Values below 3 are ignored, and the default 5 is used instead.
pay.token_type
Whether the payment is a one off payment or re-occurring. Allowed values: one-time, reusable.
pay.valid_card_types
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
Text-to-speech voice to use. Supported voices are listed in the Voice and Languages page.
When voice is not set, say_voice is used.
When neither is set, the say_voice variable is used if it is set; otherwise the voice is woman.
status_url request body
Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.
The status_url parameter is used to send requests for each status change during the payment process.
event_type
The type of event that is being reported. Will always be calling.call.pay.
event_channel
The channel that the event is being reported from.
timestamp
The timestamp of the event in the format of unix timestamp.
project_id
The project ID the event is being reported from.
space_id
The Space ID the event is being reported from.
params
An object containing the parameters of the event.
params.status_url
The URL to send requests to for each status change during the payment process.
params.status_url_method
The method to use for the requests to the status_url.
params.for
The stage of the payment process. Possible values:
payment-card-number,expiration-date,security-code,postal-code,bank-routing-number,bank-account-number- Requesting that value from the caller.payment-processing- Sending the payment details to your payment connector.payment-completed- Your payment connector returned HTTP200. A decline returned with HTTP200also sendspayment-completed, so checkpay_resultfor the outcome.payment-failed- Payment details couldn’t be collected, or your payment connector didn’t return HTTP200.payment-canceled- The caller pressed*to cancel.
params.error_type
The error type of the payment process.
params.attempt
The attempt number for the payment detail being collected, as a string (for example, "2").
Present only on events sent while collecting a payment detail.
params.payment_method
The payment method of the payment process.
params.payment_card_number
The payment card number collected so far, masked so that only the last four digits are visible (for example, ************1234).
Present only once the card number has been collected.
params.payment_card_type
The payment card type of the payment process.
params.security_code
The security code, fully masked (for example, ***). Present only once the security code has been collected.
params.expiration_date
The expiration date of the payment process.
params.bank_routing_number
The bank routing number the caller entered. Present only once it has been collected.
params.bank_account_number
The bank account number the caller entered, masked so that at most the last two digits are visible. Present only once it has been collected.
params.payment_card_postal_code
The payment card postal code of the payment process.
params.control_id
The control ID of the payment process.
params.call_id
The call ID of the payment process.
params.node_id
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.
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.
SignalWire signs this request with your project’s Signing Key. The X-SignalWire-Signature header holds the lowercase hex HMAC-SHA1 of the connector URL, with any credentials removed, followed by the raw request body, and X-SignalWire-SHA256-Signature holds the same value computed with HMAC-SHA256.
SignalWire normalizes the URL before signing it: the scheme is lowercased, . and .. path segments are resolved, and a URL without a path gets /, so https://example.com is signed as https://example.com/.
The request doesn’t come from a published IP range, so verify the signature and reject any request that doesn’t match.
For a second layer, put credentials in the URL, such as https://payuser:<LONG_RANDOM_SECRET>@pay.example.com/connector. They are sent as a standard Basic Authorization header and aren’t part of the signed URL.
A long random token in the URL path works too, and it is part of the signed URL.
The full payment_connector_url, including any credentials or token in it, is visible in your call logs in the Dashboard.
Use a secret that protects only this endpoint, and rotate it periodically.
Request body
transaction_id
Unique identifier for the transaction.
method
The payment method: credit-card or ach-debit.
cardnumber
The full card number collected from the caller. Card payments only.
cvv
The full card security code collected from the caller. Card payments only.
expiry_month
The card expiry month (e.g., 12). Card payments only.
expiry_year
The card expiry year (e.g., 99). Card payments only.
postal_code
The billing postal code: the one the caller entered, or the postal code you passed in pay.postal_code. Card payments only.
routing_number
The bank routing number collected from the caller. ach-debit payments only.
account_number
The full bank account number collected from the caller. ach-debit payments only.
account_type
The bank account type from pay.bank_account_type: consumer-checking, consumer-savings, or commercial-checking. ach-debit payments only.
chargeAmount
The amount to charge, from charge_amount, or 0.00 when charge_amount is omitted. This is the only camelCase field in the request body.
currency_code
The ISO 4217 currency code.
token_type
The token type (one-time or reusable).
description
The payment description provided in the pay method.
parameters
The custom parameters from pay.parameters, in the order you listed them.
Each name/value entry becomes an object with a single key, so {"name": "merchant_id", "value": "12345"} is sent as {"merchant_id": "12345"}.
Entries that share a name are sent as separate objects.
Present only when at least one parameter is set.
Request example
Response format
Your endpoint must respond with JSON.
SignalWire reads charge_id, token_id, error_code, and error_message from the response.
A 200 response with no error counts as a success when it carries a non-empty charge_id, or, for tokenization, a non-empty token_id.
Successful charge
Successful tokenization
Failed charge
Failed tokenization
Return a 200 HTTP status code with:
charge_id
A unique identifier for the successful transaction.
It’s available as payment_confirmation_code in pay_payment_results.
error_code
Must be null for successful transactions.
error_message
Must be null for successful transactions.
A non-200 response plays the payment-failed prompt.
A 200 response plays the payment-completed prompt even when it doesn’t count as a success, for example when its body carries an error, so check pay_result for the final outcome.
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
The overall outcome of the payment process. Possible values:
success- The payment was successful.too-many-failed-attempts- The caller exceeded themax_attemptslimit.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 theSTOPcommand.caller-hung-up- The caller hung up before completing payment.validation-error- Card details failed validation.internal-error- An internal system error occurred.failed- Thepaymethod couldn’t run or returned no payment results.pay_payment_resultsis cleared.
pay_payment_results
Detailed payment results, including card or bank account details, the token type, and any error information, stored as a JSON-encoded string.
Because the variable holds JSON text rather than an object, dot notation such as ${pay_payment_results.payment_confirmation_code} doesn’t return the fields inside it.
When decoded, the JSON object has the fields below.
pay_payment_results.result
The payment outcome. Same values as pay_result, except failed.
pay_payment_results.payment_token
For a successful tokenization, the token_id your payment connector returned. Use it for future transactions through your payment processor.
Otherwise, the token type requested in token_type: one-time or reusable.
If the caller hangs up after your payment connector has created the token, the token is still reported, with pay_result set to caller-hung-up.
pay_payment_results.payment_confirmation_code
The charge_id your payment connector returned for a successful transaction.
pay_payment_results.payment_method
The payment method used: credit-card or ach-debit.
pay_payment_results.payment_card_number
Redacted card number (e.g., ************1234).
pay_payment_results.payment_card_type
Type of card used (e.g., visa, mastercard, amex).
pay_payment_results.payment_card_expiration_date
Card expiration date (e.g., 1225 for December 2025).
pay_payment_results.payment_card_security_code
Redacted security code (e.g., ***).
pay_payment_results.payment_card_postal_code
Postal code entered by the caller.
pay_payment_results.bank_routing_number
The bank routing number the caller entered. Included only for ach-debit payments.
pay_payment_results.bank_account_number
The bank account number the caller entered, masked so that at most the last two digits are visible. Included only for ach-debit payments.
pay_payment_results.bank_account_type
The bank account type: consumer-checking, consumer-savings, or commercial-checking. Included only for ach-debit payments.
pay_payment_results.payment_error
Error description if the payment failed. Empty on success.
pay_payment_results.payment_error_code
Error code if the payment failed. Empty on success.
pay_payment_results.connector_error
Error details from the payment connector.
The object is always included; its code and message are filled in only when your connector’s response carried an error_code or error_message.
connector_error.code
Connector-specific error code.
connector_error.message
Connector-specific error message.