The <Prompt>
noun allows you to customize the default prompts used by <Pay>
.
By default, when Twilio executes <Pay>
TwiML 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 with text-to-speech or a pre-recorded audio file. For text-to-speech, you must nest <Say>
TwiML within <Prompt>
's opening and closing tags. In order to play a pre-recorded audio file, you must nest <Play>
TwiML within <Prompt>
's opening and closing tags.
There are seven payment steps in the <Pay>
process, which are listed below in the for
attribute section. You need separate <Prompt>
s for each payment step prompt that you wish to customize.
The TwiML example below shows how to use <Pay>
, <Prompt>
, and <Say>
to customize the prompt for the payment-card-number
step (i.e. when the caller is prompted to enter their payment card number) with text-to-speech.
1const VoiceResponse = require('twilio').twiml.VoiceResponse;234const response = new VoiceResponse();5const pay = response.pay();6const prompt = pay.prompt({7for: 'payment-card-number'8});9prompt.say('Please enter your 16 digit Visa or Mastercard number.');1011console.log(response.toString());
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>
The following TwiML example causes the caller to hear a pre-recorded audio file during the payment-card-number
payment step.
1const VoiceResponse = require('twilio').twiml.VoiceResponse;234const response = new VoiceResponse();5const pay = response.pay();6const prompt = pay.prompt({7for: 'payment-card-number'8});9prompt.play('https://myurl.com/twilio/twiml/audio/card_number.mp3');1011console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Pay>4<Prompt for="payment-card-number">5<Play>https://myurl.com/twilio/twiml/audio/card_number.mp3</Play>6</Prompt>7</Pay>8</Response>
The table below lists <Prompt>
's attributes. Click on an attribute name to learn more about that attribute.
Attribute Name | Allowed Values | Default Values |
---|---|---|
for required |
| none |
cardType optional |
Multiple values are allowed and must be space delimited. Example: visa amex mastercard | none |
attempt optional | An integer from 1 -10 | none |
requireMatchingInputs optional |
| false |
errorType optional |
Multiple values are allowed and must be space delimited. Example: timeout invalid-bank-account-number invalid-date | none |
<Prompt>
's for
attribute specifies which payment step's prompt you wish to customize.
The following table lists the possible values of the for
attribute, along with a description of each payment step.
Possible Value / Payment Step | Description |
---|---|
payment-card-number | The customer is asked for credit or debit card information |
expiration-date | The customer is asked for the expiration date for their payment card |
security-code | The customer is asked for the security code (CVV) for their payment card |
postal-code | The customer is asked for the postal code associated with the payment card |
bank-routing-number | The customer is asked for their bank's routing number |
bank-account-number | The customer is asked for their bank account number |
payment-processing | The payment is processing |
The cardType
attribute allows you to customize a payment step's prompt for specific payment card types.
This is useful to customize the prompt when asking for a security code, as different card types have security codes of different lengths.
The following TwiML example customizes the prompt for the security-code
payment step if the credit card number provided by the caller was a Visa card.
1const VoiceResponse = require('twilio').twiml.VoiceResponse;234const response = new VoiceResponse();5const pay = response.pay();6const prompt = pay.prompt({7for: 'security-code',8cardType: 'visa'9});10prompt.say('Please enter security code for your Visa card. It’s the 3 digits located on the back of your card');1112console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Pay>4<Prompt for="security-code" cardType="visa">5<Say> Please enter security code for your Visa card. It’s the 3 digits located on the back of your card </Say>6</Prompt>7</Pay>8</Response>
The following TwiML example customizes the prompt for the security-code
payment step if the credit card number provided by the caller was an American Express card.
1const VoiceResponse = require('twilio').twiml.VoiceResponse;234const response = new VoiceResponse();5const pay = response.pay();6const prompt = pay.prompt({7for: 'security-code',8cardType: 'amex'9});10prompt.say('Please enter security code for your American Express card. It’s the 4 digits located on the front of your card');1112console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Pay>4<Prompt for="security-code" cardType="amex">5<Say>6Please enter security code for your American Express card. It’s the 4 digits located on the front of your card7</Say>8</Prompt>9</Pay>10</Response>
If a customer fails to input a payment step's information, the customer will be prompted again to enter that step's information. You can customize what the customer hears for each attempt to gather a payment step's information using the attempt
attribute.
This can be used to provide more helpful prompts if a customer fails to enter their information after an initial prompt for a given payment step.
The TwiML example below would cause the customer to hear, "Please enter your expiration date, two digits for the month and two digits for the year." during the expiration-date
step. If the caller fails to enter an expiration date, the next <Prompt>
will execute and the caller will hear, "Please enter your expiration date, two digits for the month and two digits for the year. For example, if your expiration date is March 2022, then please enter 0 3 2 2." Since the second <Prompt>
's attempt
value is 2 3
, the caller would hear this longer prompt during a third attempt if necessary.
1const VoiceResponse = require('twilio').twiml.VoiceResponse;234const response = new VoiceResponse();5const pay = response.pay();6const prompt = pay.prompt({7for: 'expiration-date',8attempt: '1'9});10prompt.say('Please enter your expiration date, two digits for the month and two digits for the year.');11const prompt2 = pay.prompt({12for: 'expiration-date',13attempt: '2 3'14});15prompt2.say('Please enter your expiration date, two digits for the month and two digits for the year. For example, if your expiration date is March 2022, then please enter 0 3 2 2');1617console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Pay>4<Prompt for="expiration-date" attempt="1">5<Say> Please enter your expiration date, two digits for the month and two digits for the year.</Say>6</Prompt>7<Prompt for="expiration-date" attempt="2 3">8<Say> Please enter your expiration date, two digits for the month and two digits for the year. For example, if your expiration date is March 2022, then please enter 0 3 2 2 </Say>9</Prompt>10</Pay>11</Response>
The requireMatchingInputs
attribute allows you to prompt a customer to re-input their bank account number or bank routing number and tell Twilio to check whether or not the two inputs match.
The requireMatchingInputs
attribute is only available for use for ACH payments/tokenizations at this time.
Therefore, you can only use requireMatchingInputs
with for
attributes of bank-account-number
or bank-routing-number
.
If the two inputs do not match, Twilio will restart that payment step's prompts. The customer will once again hear the first prompt to enter their information and the second prompt to re-enter the information.
1const VoiceResponse = require('twilio').twiml.VoiceResponse;23const response = new VoiceResponse();4const pay = response.pay({5paymentMethod: 'ach-debit',6chargeAmount: '13.22'7});8const prompt = pay.prompt({9for: 'bank-account-number'10});11prompt.say('Thanks for using our service. Please enter your bank account number.');12const prompt2 = pay.prompt({13for: 'bank-account-number',14requireMatchingInputs: true15});16prompt2.say('Thank you. Please enter your bank account number again.');1718console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Pay paymentMethod="ach-debit" chargeAmount="13.22">4<Prompt for="bank-account-number">5<Say>Thanks for using our service. Please enter your bank account number.</Say>6</Prompt>7<Prompt for="bank-account-number" requireMatchingInputs="true">8<Say>Thank you. Please enter your bank account number again.</Say>9</Prompt>10</Pay>11</Response>
You should use two <Prompt>
s with the same for
attribute. The second <Prompt>
should have requireMatchingInputs
set to true
. This will give the caller two different prompts: one to enter a piece of information once, and one that tells the caller to re-enter the information for verification purposes.
Optionally, you can use a third <Prompt>
(with the same for
attribute) with the errorType
attribute set to input-matching-failed
to customize the prompt the caller hears if their inputs did not match. The TwiML example below illustrates this behavior.
1const VoiceResponse = require('twilio').twiml.VoiceResponse;23const response = new VoiceResponse();4const pay = response.pay({5paymentMethod: 'ach-debit',6chargeAmount: '13.22'7});8const prompt = pay.prompt({9for: 'bank-account-number'10});11prompt.say('Thanks for using our service. Please enter your bank account number.');12const prompt2 = pay.prompt({13for: 'bank-account-number',14requireMatchingInputs: true15});16prompt2.say('Thank you. Please enter your bank account number again.');17const prompt3 = pay.prompt({18for: 'bank-account-number',19errorType: 'input-matching-failed'20});21prompt3.say('Sorry, your two bank account number inputs did not match. Please enter your bank account number again. We will then ask a second time again.');2223console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Pay paymentMethod="ach-debit" chargeAmount="13.22">4<Prompt for="bank-account-number">5<Say>Thanks for using our service. Please enter your bank account number.</Say>6</Prompt>7<Prompt for="bank-account-number" requireMatchingInputs="true">8<Say>Thank you. Please enter your bank account number again.</Say>9</Prompt>10<Prompt for="bank-account-number" errorType="input-matching-failed">11<Say>Sorry, your two bank account number inputs did not match. Please enter your bank account number again. We will then ask a second time again.</Say>12</Prompt>13</Pay>14</Response>
The errorType
attribute allows you to customize the prompt that the caller hears if their input for a given payment step was invalid.
The following are possible values of errorType
and descriptions of the cause of the error.
errorType | Description |
---|---|
timeout | <Pay> received a timeout when executing a payment step |
invalid-card-number | <Pay> didn't receive the appropriate number of digits for either credit card number, expiration date, security code or zip code. Or card number entered didn't pass the validation. This reason can be used to apply further customization on the message to play such as informing payee/caller that the incorrect number of digits were entered. |
invalid-card-type | The card number entered didn't match the accepted card types. For example, if only visa or mastercard are accepted and payee enters amex, InvalidReason parameter will contain this value. |
invalid-date | <Pay> didn't receive the correct number of digits for the date. |
invalid-security-code | This reason is generated when the payee entered an invalid security code. For example, if credit card number is amex and user entered 3 digits for the security code. |
invalid-postal-code | <Pay> didn't receive the correct number of digits for the postal/zip code. |
invalid-bank-routing-number | <Pay> either didn't receive the appropriate number of digits for the routing number or the routing number provided failed the validation performed by <Pay> . |
invalid-bank-account-number | <Pay> didn't receive the minimum number of digits required for the bank account number. |
input-matching-failed | The first and second inputs by the customer did not match. Only will be returned when requireMatchingInputs is set to true . Only available for ACH payments/tokenizations at this time. |
The following examples show the TwiML you can use to customize all prompts for <Pay>
when accepting a credit card payment:
1const VoiceResponse = require('twilio').twiml.VoiceResponse;23const response = new VoiceResponse();4const pay = response.pay({5paymentMethod: 'credit-card',6validCardTypes: 'visa mastercard amex'7});8const prompt = pay.prompt({9for: 'payment-card-number'10});11prompt.say('Please enter your credit card number.');12const prompt2 = pay.prompt({13for: 'payment-card-number',14errorType: 'timeout'15});16prompt2.say('You didn\'t enter your credit card number. Please enter your credit card number.');17const prompt3 = pay.prompt({18for: 'payment-card-number',19errorType: 'invalid-card-number'20});21prompt3.say('You entered an invalid credit card number. Please try again.');22const prompt4 = pay.prompt({23for: 'payment-card-number',24errorType: 'invalid-card-type'25});26prompt4.say('The card number you entered isn\'t from one of our accepted credit card issuers. Please enter a Visa, MasterCard, or American Express credit card number.');27const prompt5 = pay.prompt({28for: 'expiration-date'29});30prompt5.say('Please enter your credit card\'s expiration date. Two digits for the month and two digits for the year.');31const prompt6 = pay.prompt({32for: 'expiration-date',33errorType: 'timeout'34});35prompt6.say('Sorry. You didn\'t enter an expiration date. Please enter your card\'s expiration date. Two digits for the month and two digits for the year.');36const prompt7 = pay.prompt({37for: 'expiration-date',38errorType: 'invalid-date'39});40prompt7.say('The date you entered was incorrect or is in the past. Please enter the expiration date. Two digits for the month and two digits for the year. For example, to enter July twenty twenty two, enter 0 7 2 2.');41const prompt8 = pay.prompt({42for: 'security-code',43cardType: 'visa mastercard'44});45prompt8.say('Please enter your security code. It\'s the 3 digits located on the back of your card.');46const prompt9 = pay.prompt({47for: 'security-code',48errorType: 'timeout',49cardType: 'visa mastercard'50});51prompt9.say('You didn\'t enter your credit card security code. Please enter your security code. It\'s the 3 digits located on the back of your card.');52const prompt10 = pay.prompt({53for: 'security-code',54errorType: 'invalid-security-code',55cardType: 'visa mastercard'56});57prompt10.say('That was an invalid security code. The security code must be 3 digits. Please try again.');58const prompt11 = pay.prompt({59for: 'security-code',60cardType: 'amex'61});62prompt11.say('Please enter your security code. It\'s the 4 digits located on the front of your card.');63const prompt12 = pay.prompt({64for: 'security-code',65errorType: 'timeout',66cardType: 'amex'67});68prompt12.say('You didn\'t enter your credit card security code. Please enter your security code. It\'s the 4 digits located on the front of your card.');69const prompt13 = pay.prompt({70for: 'security-code',71errorType: 'invalid-security-code',72cardType: 'amex'73});74prompt13.say('That was an invalid security code. The security code must be 4 digits. Please try again.');75const prompt14 = pay.prompt({76for: 'postal-code'77});78prompt14.say('Please enter your 5 digit billing zip code.');79const prompt15 = pay.prompt({80for: 'postal-code',81errorType: 'timeout'82});83prompt15.say('You didn\'t enter your billing zip code. Please enter your 5 digit billing zip code.');84const prompt16 = pay.prompt({85for: 'payment-processing'86});87prompt16.say('Thank you. Please wait while we process your payment.');8889console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Pay paymentMethod="credit-card" validCardTypes="visa mastercard amex">4<!-- Prompts for credit card number -->5<Prompt for="payment-card-number">6<Say>Please enter your credit card number.</Say>7</Prompt>8<Prompt for="payment-card-number" errorType="timeout">9<Say>You didn't enter your credit card number. Please enter your credit card number.</Say>10</Prompt>11<Prompt for="payment-card-number" errorType="invalid-card-number">12<Say>You entered an invalid credit card number. Please try again.</Say>13</Prompt>14<Prompt for="payment-card-number" errorType="invalid-card-type">15<Say>The card number you entered isn't from one of our accepted credit card issuers. Please enter a Visa, MasterCard, or American Express credit card number.</Say>16</Prompt>17<!-- Prompts for expiration date -->18<Prompt for="expiration-date">19<Say>Please enter your credit card's expiration date. Two digits for the month and two digits for the year.</Say>20</Prompt>21<Prompt for="expiration-date" errorType="timeout">22<Say>Sorry. You didn't enter an expiration date. Please enter your card's expiration date. Two digits for the month and two digits for the year.</Say>23</Prompt>24<Prompt for="expiration-date" errorType="invalid-date">25<Say>The date you entered was incorrect or is in the past. Please enter the expiration date. Two digits for the month and two digits for the year. For example, to enter July twenty twenty two, enter 0 7 2 2.</Say>26</Prompt>27<!-- Prompts for three-digit security code -->28<Prompt for="security-code" cardType="visa mastercard">29<Say>Please enter your security code. It's the 3 digits located on the back of your card.</Say>30</Prompt>31<Prompt for="security-code" errorType="timeout" cardType="visa mastercard">32<Say>You didn't enter your credit card security code. Please enter your security code. It's the 3 digits located on the back of your card.</Say>33</Prompt>34<Prompt for="security-code" errorType="invalid-security-code" cardType="visa mastercard">35<Say>That was an invalid security code. The security code must be 3 digits. Please try again.</Say>36</Prompt>37<!-- Prompts for four-digit security code (American Express) -->38<Prompt for="security-code" cardType="amex">39<Say>Please enter your security code. It's the 4 digits located on the front of your card.</Say>40</Prompt>41<Prompt for="security-code" errorType="timeout" cardType="amex">42<Say>You didn't enter your credit card security code. Please enter your security code. It's the 4 digits located on the front of your card.</Say>43</Prompt>44<Prompt for="security-code" errorType="invalid-security-code" cardType="amex">45<Say>That was an invalid security code. The security code must be 4 digits. Please try again.</Say>46</Prompt>47<!-- Prompts for postal/zip code -->48<Prompt for="postal-code">49<Say>Please enter your 5 digit billing zip code.</Say>50</Prompt>51<Prompt for="postal-code" errorType="timeout">52<Say>You didn't enter your billing zip code. Please enter your 5 digit billing zip code.</Say>53</Prompt>54<!-- Prompt after customer has entered all payment information -->55<Prompt for="payment-processing">56<Say>Thank you. Please wait while we process your payment.</Say>57</Prompt>58</Pay>59</Response>
The following examples show the TwiML you can use to customize all prompts for <Pay>
when accepting an ACH payment:
1const VoiceResponse = require('twilio').twiml.VoiceResponse;23const response = new VoiceResponse();4const pay = response.pay({5timeout: '5',6maxAttempts: '3',7paymentMethod: 'ach-debit',8language: 'en-US'9});10const prompt = pay.prompt({11for: 'bank-routing-number'12});13prompt.say('Please enter your bank routing number.');14const prompt2 = pay.prompt({15for: 'bank-routing-number',16errorType: 'timeout'17});18prompt2.say('You didn\'t enter your routing number. Please enter your bank routing number.');19const prompt3 = pay.prompt({20for: 'bank-routing-number',21errorType: 'invalid-bank-routing-number'22});23prompt3.say('That was an invalid bank routing number. Please try again.');24const prompt4 = pay.prompt({25for: 'bank-account-number'26});27prompt4.say('Please enter your bank account number.');28const prompt5 = pay.prompt({29for: 'bank-account-number',30errorType: 'timeout'31});32prompt5.say('You didn\'t enter your bank account number. Please enter your bank account number.');33const prompt6 = pay.prompt({34for: 'payment-processing'35});36prompt6.say('Thank you. Please wait while we process your payment.');3738console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Pay timeout="5" maxAttempts="3" paymentMethod="ach-debit" language="en-US">4<Prompt for="bank-routing-number">5<Say>Please enter your bank routing number.</Say>6</Prompt>7<Prompt for="bank-routing-number" errorType="timeout">8<Say>You didn't enter your routing number. Please enter your bank routing number.</Say>9</Prompt>10<Prompt for="bank-routing-number" errorType="invalid-bank-routing-number">11<Say>That was an invalid bank routing number. Please try again.</Say>12</Prompt>13<Prompt for="bank-account-number">14<Say>Please enter your bank account number.</Say>15</Prompt>16<Prompt for="bank-account-number" errorType="timeout">17<Say>You didn't enter your bank account number. Please enter your bank account number.</Say>18</Prompt>19<Prompt for="payment-processing">20<Say>Thank you. Please wait while we process your payment.</Say>21</Prompt>22</Pay>23</Response>