Prompts Object

The prompts object allows you to customize 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.

Properties

Name	Type	Description
actionsRequired	object[]	Array of action objects to execute for this prompt. These actions can either play an audio file or speak a phrase.
forRequired	string	The payment step this prompt is for. See Payment Steps for a list of available steps.
attemptsOptional	string	Specifies 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 the specific attempts.
card_typeOptional	string	Space-separated list of card types this prompt applies to. Allowed Values: visa mastercard amex maestro discover optima jcb diners-club
error_typeOptional	string	Space-separated list of error types this prompt applies to. See Error Types.

Payment steps

The for property indicates which payment step the prompt is for. None of these steps are required in your custom prompts - any omitted steps will use default prompts.

note

For example, if security-code is set to false, then the security code step will be skipped.

Step	Description	Default Prompt
payment-card-numberOptional	Collect the payment card number.	"Please enter your credit card number"
expiration-dateOptional	Collect the payment card expiration date.	"Please enter your credit card's expiration date. 2 digits for the month and 2 digits for the year"
security-codeOptional	Collect the payment card security code.	"Please enter your credit card's security code. It's the 3 digits located on the back of your card"
postal-codeOptional	Collect the payment card postal code.	"Please enter your billing postal code"
payment-processingOptional	The step used during the payment processing.	"Payment processing. Please wait"
payment-completedOptional	The step used when the payment is completed.	"Payment completed. Thank you"
payment-failedOptional	The step used when the payment fails.	"Payment failed"
payment-canceledOptional	The step used when the payment is cancelled.	"Payment canceled"

Error types

The error_type property can include any of these values:

Error Type	Description
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
card-declined	Payment declined

Example

YAML

version: 1.0.0
sections:
  main:
    - pay:
        payment_connector_url: "https://example.com/process"
        prompts:
          - for: "payment-card-number"
            actions:
              - type: "Say"
                phrase: "Welcome to SignalWire telephony payment gateway!"
              - type: "Say"
                phrase: "You are going to pay your monthly subscription fee"
              - type: "Say"
                phrase: "Please enter your credit card number"
          - for: "payment-card-number"
            error_type: "invalid-card-number timeout invalid-card-type"
            actions:
              - type: "Say"
                phrase: "You entered an invalid credit card number. Please try again."
          - for: "payment-completed"
            actions:
              - type: "Say"
                phrase: "Payment completed. You can continue to use our services."

JSON

{
  "version": "1.0.0",
  "sections": {
    "main": [
      {
        "pay": {
          "payment_connector_url": "https://example.com/process",
          "prompts": [
            {
              "for": "payment-card-number",
              "actions": [
                {
                  "type": "Say",
                  "phrase": "Welcome to SignalWire telephony payment gateway!"
                },
                {
                  "type": "Say",
                  "phrase": "You are going to pay your monthly subscription fee"
                },
                {
                  "type": "Say",
                  "phrase": "Please enter your credit card number"
                }
              ]
            },
            {
              "for": "payment-card-number",
              "error_type": "invalid-card-number timeout invalid-card-type",
              "actions": [
                {
                  "type": "Say",
                  "phrase": "You entered an invalid credit card number. Please try again."
                }
              ]
            },
            {
              "for": "payment-completed",
              "actions": [
                {
                  "type": "Say",
                  "phrase": "Payment completed. You can continue to use our services."
                }
              ]
            }
          ]
        }
      }
    ]
  }
}