Skip to main content
Get startedGuidesTechnical Reference

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.

pay
objectrequired

An object that accepts the pay parameters.

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.

note

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"

Parameters​

pay.payment_connector_url
stringrequired

The URL to make POST requests with all the gathered payment details. This URL is used to process the final payment transaction and return the results through the response. Visit the payment_connector_url page for more important details.

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
string
Default: 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
string
Default: dtmf

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

pay.language
string
Default: 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
integer
Default: 1

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

pay.min_postal_code_length
integer
Default: 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.

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|string
Default: 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 during different stages of the payment process.

pay.security_code
boolean
Default: 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
integer
Default: 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
string
Default: reusable

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

pay.valid_card_types
string
Default: visa mastercard amex

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

pay.voice
string
Default: 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.

{
  "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"
  }
}

Variables​

The following variables are available after the payment process completes:

pay_payment_results
object

An object containing the payment results of the payment process. Please refer to the pay_payment_results section for more details.

pay_result
string

The result of the payment process. Please refer to the pay_result section for possible values.

pay_payment_results​

payment_token
string

Payment token from processor

payment_confirmation_code
string

Confirmation code for the transaction

payment_card_number
string

Redacted card number

payment_card_type
string

Type of card used

payment_card_expiration_date
string

Card expiration date

payment_card_security_code
string

Redacted security code

payment_card_postal_code
string

Postal code used

payment_error
string

Error description if payment failed

payment_error_code
string

Error code if payment failed

connector_error
object

Connector-specific error object

connector_error.code
string

Connector-specific error code

connector_error.message
string

Connector-specific error message

Example​

{
  "payment_token": "1234567890",
  "payment_confirmation_code": "1234567890",
  "payment_card_number": "1234567890",
  "payment_card_type": "visa",
  "payment_card_expiration_date": "12/2025",
  "payment_card_security_code": "123",
  "payment_card_postal_code": "12345",
  "payment_error": "Invalid card number",
  "payment_error_code": "invalid-card-number",
  "connector_error": {
    "code": "invalid-card-number",
    "message": "Invalid card number"
  }
}

pay_result​

success
string

The payment was successful.

too-many-failed-attempts
string

The payment failed because the caller entered too many failed attempts.

payment-connector-error
string

The payment failed because of an error from the payment connector.

caller-interrupted-with-star
string

The payment failed because the caller interrupted the payment process with a * key.

relay-pay-stop
string

The payment failed because the caller stopped the payment process with the STOP command.

caller-hung-up
string

The payment failed because the caller hung up.

validation-error
string

The payment failed because of a validation error.

internal-error
string

The payment failed because of an internal error.

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

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"