VoicePay

Prompt

View as Markdown

The <Prompt> noun allows you to customize the default prompts used by <Pay>.

When SignalWire executes <Pay> CXML instructions without <Prompt>, the caller will hear default prompts for each step of the payment process. You can modify what the caller hears for a given payment step by nesting <Prompt> within <Pay>’s opening and closing tags.

You can customize prompts using either:

  • Text-to-speech by nesting <Say> CXML within <Prompt>
  • Pre-recorded audio by nesting <Play> CXML within <Prompt>

Payment steps

There are seven payment steps in the <Pay> process where prompts can be customized (see the for attribute section below). Each step that you wish to customize requires its own <Prompt> element.

Attributes

for
stringRequired

Specifies which payment step’s prompt you wish to customize. Allowed values: payment-card-number, expiration-date, security-code, postal-code, bank-routing-number, bank-account-number, payment-processing. See Payment Steps for details.

attempt
integer

Specifies which attempt number this prompt should be used for. Value from 1 to 10. Useful for providing more detailed instructions after failed attempts.

cardType
string

Space-separated list of card types. Allows customization of prompts for specific card types (e.g., different security code lengths). Allowed values: visa, mastercard, amex, maestro, discover, optima, jcb, diners-club, enroute.

errorType
string

Space-separated list of error types. Customize error messages for specific failure scenarios. Allowed values: timeout, invalid-card-number, invalid-card-type, invalid-date, invalid-security-code, invalid-bank-routing-number, invalid-bank-account-number, input-matching-failed.

Payment step

Specifies which payment step’s prompt you wish to customize:

Payment StepDescription
payment-card-numberPrompt for credit/debit card number
expiration-datePrompt for card expiration date
security-codePrompt for card security code (CVV)
postal-codePrompt for billing postal code
bank-routing-numberPrompt for bank routing number
bank-account-numberPrompt for bank account number
payment-processingMessage during payment processing

Examples

Prompt for card number with TTS

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Pay>
4   <Prompt for="payment-card-number">
5     <Say>Please enter your 16 digit Visa or Mastercard number.</Say>
6   </Prompt>
7  </Pay>
8</Response>

Prompt for card number with MP3

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Pay>
4   <Prompt for="payment-card-number">
5     <Play>https://example.com/signalwire/cxml/audio/card_number.mp3</Play>
6   </Prompt>
7  </Pay>
8</Response>

Full transaction example

1<?xml version="1.0" encoding="UTF-8"?>
2<Response>
3  <Pay paymentMethod="credit-card" validCardTypes="visa mastercard amex">
4    
5    <Prompt for="payment-card-number">
6      <Say>Welcome! To begin, enter the credit card number you'd like to use for payment.</Say>
7    </Prompt>
8    <Prompt for="payment-card-number" errorType="timeout">
9      <Say>I haven't received your card number yet. Please take a moment to enter your credit card number now.</Say>
10    </Prompt>
11    <Prompt for="payment-card-number" errorType="invalid-card-number">
12      <Say>That card number doesn't appear to be valid. Let's try entering it one more time.</Say>
13    </Prompt>
14    <Prompt for="payment-card-number" errorType="invalid-card-type">
15      <Say>We can only accept Visa, MasterCard, or American Express cards. Please enter a card number from one of these providers.</Say>
16    </Prompt>
17    
18    <Prompt for="expiration-date">
19      <Say>Great! Now enter your card's expiration date using two digits for the month followed by two digits for the year.</Say>
20    </Prompt>
21    <Prompt for="expiration-date" errorType="timeout">
22      <Say>I still need your card's expiration date. Please enter two digits for the month, then two digits for the year.</Say>
23    </Prompt>
24    <Prompt for="expiration-date" errorType="invalid-date">
25      <Say>That expiration date isn't valid. Remember to use two digits each for month and year - for example, March 2025 would be 0 3 2 5.</Say>
26    </Prompt>
27    
28    <Prompt for="security-code" cardType="visa mastercard">
29      <Say>Now for the security code - you'll find three digits on the back of your card.</Say>
30    </Prompt>
31    <Prompt for="security-code" errorType="timeout" cardType="visa mastercard">
32      <Say>I'm waiting for your three-digit security code. You can find it on the back of your card.</Say>
33    </Prompt>
34    <Prompt for="security-code" errorType="invalid-security-code" cardType="visa mastercard">
35      <Say>That security code wasn't quite right. Please enter all three digits from the back of your card.</Say>
36    </Prompt>
37    
38    <Prompt for="security-code" cardType="amex">
39      <Say>For American Express, please enter the four-digit security code from the front of your card.</Say>
40    </Prompt>
41    <Prompt for="security-code" errorType="timeout" cardType="amex">
42      <Say>I still need the four-digit security code from the front of your American Express card.</Say>
43    </Prompt>
44    <Prompt for="security-code" errorType="invalid-security-code" cardType="amex">
45      <Say>That security code wasn't valid. Please enter all four digits from the front of your American Express card.</Say>
46    </Prompt>
47    
48    <Prompt for="postal-code">
49      <Say>Almost done! Please enter the five-digit zip code for your billing address.</Say>
50    </Prompt>
51    <Prompt for="postal-code" errorType="timeout">
52      <Say>We still need your billing zip code. Please enter all five digits now.</Say>
53    </Prompt>
54    
55    <Prompt for="payment-processing">
56      <Say>Perfect! Just a moment while we securely process your payment.</Say>
57    </Prompt>
58  </Pay>
59</Response>