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.

Name	Type	Default	Description
`pay`Required	`object`	-	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.

YAML
JSON

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

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "pay": {
          "charge_amount": 25,
          "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.

YAML
JSON

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

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "pay": {
          "charge_amount": 0,
          "payment_connector_url": "https://example.com/process"
        }
      }
    ]
  }
}

Parameters

Name	Type	Default	Description
`payment_connector_url`Required	`string`	-	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.
`charge_amount`Optional	`string`	-	The amount to charge against payment method passed in the request. `Float` value with no currency prefix passed as string.
`currency`Optional	`string`	`usd`	Uses the ISO 4217 currency code of the charge amount.
`description`Optional	`string`	-	Custom description of the payment provided in the request.
`input`Optional	`string`	`dtmf`	The method of how to collect the payment details. Currently only `dtmf` mode is supported.
`language`Optional	`string`	`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.
`max_attempts`Optional	`integer`	`1`	Number of times the `pay` method will retry to collect payment details.
`min_postal_code_length`Optional	`integer`	`0`	The minimum length of the postal code the user must enter.
`parameters`Optional	`object[]`	-	Array of parameter objects to pass to your payment processor.
`payment_method`Optional	`string`	-	Indicates the payment method which is going to be used in this payment request. Currently only `credit-card` is supported.
`postal_code`Optional	`boolean\|string`	`true`	Takes true, false or real postcode (if it's known beforehand) to let pay method know whether to prompt for postal code.
`prompts`Optional	`object[]`	-	Array of prompt objects for customizing the audio prompts during different stages of the payment process.
`security_code`Optional	`boolean`	`true`	Takes true or false to let pay method know whether to prompt for security code.
`status_url`Optional	`string`	-	The URL to send requests for each status change during the payment process. See the status_url request body section for more details.
`timeout`Optional	`integer`	`5`	Limit in seconds that pay method waits for the caller to press another digit before moving on to validate the digits captured.
`token_type`Optional	`string`	`reusable`	Whether the payment is a one off payment or re-occurring. Allowed values: `one-time`, `reusable`.
`valid_card_types`Optional	`string`	`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`.
`voice`Optional	`string`	`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.

Name	Type	Description
`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:

Name	Type	Description
`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

Name	Type	Description
`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

Name	Type	Description
`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

YAML
JSON

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

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

YAML
JSON

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

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "pay": {
          "token_type": "reusable",
          "charge_amount": "0",
          "payment_connector_url": "https://example.com/tokenize"
        }
      }
    ]
  }
}

Retry logic

YAML
JSON

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

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

YAML
JSON

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"

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

Transaction Types​

Charges​

Tokenization​

Parameters​

status_url request body​

Request format​

Variables​

pay_payment_results​

Example​

pay_result​

Examples​

Simple payment collection​

Basic tokenization​

Retry logic​

International payment with custom prompts​