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.

pay.prompts

object[]

Array of prompt objects that accept the prompts properties.

Properties

prompts[].actions

object[]required

Array of action objects to execute for this prompt. These actions can either play an audio file or speak a phrase.

prompts[].for

stringrequired

The payment step this prompt is for.

See Payment Steps for a list of available steps.

prompts[].attempts

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.

prompts[].card_type

string

Space-separated list of card types this prompt applies to.
Allowed Values:

• visa
• mastercard
• amex
• maestro
• discover
• optima
• jcb
• diners-club

prompts[].error_type

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.

payment-card-number

Optional

Default: Please enter your credit card number

Collect the payment card number.

expiration-date

Optional

Default: Please enter your credit card's expiration date. 2 digits for the month and 2 digits for the year

Collect the payment card expiration date.

security-code

Optional

Default: Please enter your credit card's security code. It's the 3 digits located on the back of your card

Collect the payment card security code.

postal-code

Optional

Default: Please enter your billing postal code

Collect the payment card postal code.

payment-processing

Optional

Default: Payment processing. Please wait

The step used during the payment processing.

payment-completed

Optional

Default: Payment completed. Thank you

The step used when the payment is completed.

payment-failed

Optional

Default: Payment failed

The step used when the payment fails.

payment-canceled

Optional

Default: Payment canceled

The step used when the payment is cancelled.

Error types

The error_type property can include any of these values:

timeout

string

User input timeout

invalid-card-number

string

Failed card validation

invalid-card-type

string

Unsupported card type

invalid-date

string

Invalid expiration date

invalid-security-code

string

Invalid CVV format

invalid-postal-code

string

Invalid postal code format

session-in-progress

string

Concurrent session attempt

card-declined

string

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