Skip to navigation
Calling

pay

View as MarkdownOpen in Claude

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.

version: 1.0.0
sections:
main:
- pay:
charge_amount: "25.00"
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. 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.

version: 1.0.0
sections:
main:
- pay:
charge_amount: "0"
payment_connector_url: "https://example.com/process"

Properties

pay
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. 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
stringDefaults to 0.00

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
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.

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
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 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
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. See the payment connector request body for how they’re sent.

parameters[].name
stringRequired

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
stringRequired

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
stringDefaults to credit-card

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
stringDefaults to consumer-checking

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
stringDefaults to true

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_code on, 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
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”
  • 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 HTTP 200. Check pay_result for 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 than 200. Default: “Payment failed”
  • payment-canceled - Played when payment is cancelled. Default: “Payment canceled”
prompts[].actions
object[]

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
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[].play
object[]

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
stringRequired

The type of media to play. Allowed values: audio, tts, silence, ringtone.

play[].params
objectRequired

Parameters for the media item. Which properties apply depends on type.

params.url
string

Required when type is audio. HTTP or HTTPS URL of the audio file to play.

params.text
string

Required when type is tts. The text to speak.

params.language
string

Used when type is tts. Language code for the speech, such as en-US. Falls back to the pay method’s language.

params.gender
string

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
string

Used when type is tts. Text-to-speech voice. Falls back to the pay method’s voice.

params.duration
number

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
string

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
stringDefaults to 1 2 3

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
string

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
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
  • invalid-bank-routing-number - Invalid bank routing number
  • invalid-bank-account-number - Invalid bank account number
  • input-matching-failed - Input matching failed. Accepted, but pay doesn’t currently report this error
  • card-declined - Payment declined
  • bank-account-declined - Bank account payment declined
  • invalid-bank-account-type - Unsupported bank account type
pay.say_voice
string

Alternative name for voice. Used only when voice is not set.

pay.security_code
stringDefaults to true

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
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. 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
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. 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 advisory

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
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 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 HTTP 200. A decline returned with HTTP 200 also sends payment-completed, so check pay_result for the outcome.
  • payment-failed - Payment details couldn’t be collected, or your payment connector didn’t return HTTP 200.
  • payment-canceled - The caller pressed * to cancel.
params.error_type
string

The error type of the payment process.

params.attempt
string

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
string

The payment method of the payment process.

params.payment_card_number
string

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
string

The payment card type of the payment process.

params.security_code
string

The security code, fully masked (for example, ***). Present only once the security code has been collected.

params.expiration_date
string

The expiration date of the payment process.

params.bank_routing_number
string

The bank routing number the caller entered. Present only once it has been collected.

params.bank_account_number
string

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
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.

{
"event_type": "calling.call.pay",
"event_channel": "swml:XXXX-XXXX-XXXX-XXXX-XXXX",
"timestamp": 1743707517.12267,
"project_id": "XXXX-XXXX-XXXX-XXXX-XXXX",
"space_id": "XXXX-XXXX-XXXX-XXXX-XXXX",
"params": {
"status_url": "https://example.com/status",
"status_url_method": "POST",
"for": "payment-completed",
"error_type": "",
"payment_method": "credit-card",
"payment_card_number": "************1234",
"payment_card_type": "visa",
"security_code": "***",
"expiration_date": "1225",
"payment_card_postal_code": "23112",
"control_id": "XXXX-XXXX-XXXX-XXXX-XXXX",
"call_id": "XXXX-XXXX-XXXX-XXXX-XXXX",
"node_id": "XXXX-XXXX-XXXX-XXXX-XXXX"
}
}

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 connector URL appears in your call logs

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
string

Unique identifier for the transaction.

method
string

The payment method: credit-card or ach-debit.

cardnumber
string

The full card number collected from the caller. Card payments only.

cvv
string

The full card security code collected from the caller. Card payments only.

expiry_month
string

The card expiry month (e.g., 12). Card payments only.

expiry_year
string

The card expiry year (e.g., 99). Card payments only.

postal_code
string

The billing postal code: the one the caller entered, or the postal code you passed in pay.postal_code. Card payments only.

routing_number
string

The bank routing number collected from the caller. ach-debit payments only.

account_number
string

The full bank account number collected from the caller. ach-debit payments only.

account_type
string

The bank account type from pay.bank_account_type: consumer-checking, consumer-savings, or commercial-checking. ach-debit payments only.

chargeAmount
string

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
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.

parameters
object[]

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

{
"transaction_id": "8c9d14d5-52ae-4e2e-b880-a14e6e1cda7d",
"method": "credit-card",
"cardnumber": "4242424242424242",
"cvv": "123",
"postal_code": "123456",
"description": "Payment description",
"chargeAmount": "10.55",
"token_type": "reusable",
"expiry_month": "12",
"expiry_year": "99",
"currency_code": "usd",
"parameters": [
{ "merchant_id": "12345" }
]
}

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.

Return a 200 HTTP status code with:

charge_id
string

A unique identifier for the successful transaction. It’s available as payment_confirmation_code in pay_payment_results.

error_code
null

Must be null for successful transactions.

error_message
null

Must be null for successful transactions.

{
"charge_id": "ch_123456789",
"error_code": null,
"error_message": null
}

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
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.
  • failed - The pay method couldn’t run or returned no payment results. pay_payment_results is cleared.
pay_payment_results
string

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
string

The payment outcome. Same values as pay_result, except failed.

pay_payment_results.payment_token
string

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
string

The charge_id your payment connector returned for a successful transaction.

pay_payment_results.payment_method
string

The payment method used: credit-card or ach-debit.

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.bank_routing_number
string

The bank routing number the caller entered. Included only for ach-debit payments.

pay_payment_results.bank_account_number
string

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
string

The bank account type: consumer-checking, consumer-savings, or commercial-checking. Included only for ach-debit payments.

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 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
string

Connector-specific error code.

connector_error.message
string

Connector-specific error message.

Examples

Simple payment collection

version: 1.0.0
sections:
main:
- pay:
charge_amount: '20.45'
payment_connector_url: "https://example.com/process"
status_url: "https://example.com/status"

Basic tokenization

version: 1.0.0
sections:
main:
- pay:
token_type: "reusable"
charge_amount: '0'
payment_connector_url: "https://example.com/tokenize"

Retry logic

version: 1.0.0
sections:
main:
- pay:
charge_amount: '75.00'
payment_connector_url: "https://example.com/process"
max_attempts: 3
timeout: 10

Custom parameters

version: 1.0.0
sections:
main:
- pay:
charge_amount: "10.00"
payment_connector_url: "https://example.com/process"
parameters:
- name: "my_custom_parameter_1"
value: "my_custom_value_1"

International payment with custom prompts

version: 1.0.0
sections:
main:
- pay:
charge_amount: '100.00'
payment_connector_url: "https://example.com/process"
currency: "pln"
language: "pl-PL"
description: "Polish zloty transaction"
prompts:
- for: "payment-card-number"
actions:
- type: "Say"
phrase: "Witamy w telefonicznym systemie płatności"
- type: "Say"
phrase: "Proszę wprowadzić numer karty płatniczej"
- for: "payment-card-number"
error_type: "invalid-card-number timeout invalid-card-type"
actions:
- type: "Say"
phrase: "Wprowadziłeś błędny numer karty płatniczej. Proszę spróbować ponownie"
- for: "payment-completed"
actions:
- type: "Say"
phrase: "Płatność zakończona powodzeniem"

Bank account payment with play prompts

version: 1.0.0
sections:
main:
- pay:
charge_amount: "50.00"
payment_connector_url: "https://example.com/process"
payment_method: "ach-debit"
bank_account_type: "consumer-savings"
prompts:
- for: "bank-routing-number"
play:
- type: "tts"
params:
text: "Please enter the nine digit routing number for your savings account."
- for: "bank-account-number"
play:
- type: "silence"
params:
duration: 0.5
- type: "tts"
params:
text: "Now enter your savings account number, then press pound."

Handling payment results

version: 1.0.0
sections:
main:
- answer: {}
- pay:
charge_amount: '25.00'
payment_connector_url: "https://example.com/process"
- cond:
- when: "pay_result == 'success'"
then:
- play:
url: 'say: Payment successful. Thank you.'
- else:
- play:
url: 'say: Payment was not completed. Please try again later.'