The TwiML's <Pay> Verb's <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.
prompt.say('Please enter security code for your Visa card. It’s the 3 digits located on the back of your card');
_12
_12
console.log(response.toString());
Output
_10
<?xml version="1.0" encoding="UTF-8"?>
_10
<Response>
_10
<Pay>
_10
<Prompt for="security-code" cardType="visa">
_10
<Say> Please enter security code for your Visa card. It’s the 3 digits located on the back of your card </Say>
_10
</Prompt>
_10
</Pay>
_10
</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.
Prompt for an American Express security code (4 digits)
prompt.say('Please enter security code for your American Express card. It’s the 4 digits located on the front of your card');
_12
_12
console.log(response.toString());
Output
_10
<?xml version="1.0" encoding="UTF-8"?>
_10
<Response>
_10
<Pay>
_10
<Prompt for="security-code" cardType="amex">
_10
<Say>
_10
Please enter security code for your American Express card. It’s the 4 digits located on the front of your card
_10
</Say>
_10
</Prompt>
_10
</Pay>
_10
</Response>
attempt
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.
prompt.say('Please enter your expiration date, two digits for the month and two digits for the year.');
_17
const prompt2 = pay.prompt({
_17
for: 'expiration-date',
_17
attempt: '2 3'
_17
});
_17
prompt2.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');
_17
_17
console.log(response.toString());
Output
_11
<?xml version="1.0" encoding="UTF-8"?>
_11
<Response>
_11
<Pay>
_11
<Prompt for="expiration-date" attempt="1">
_11
<Say> Please enter your expiration date, two digits for the month and two digits for the year.</Say>
_11
</Prompt>
_11
<Prompt for="expiration-date" attempt="2 3">
_11
<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>
_11
</Prompt>
_11
</Pay>
_11
</Response>
requireMatchingInputs
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.
(warning)
Warning
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.
Require caller to enter bank account information twice
<Say>Thank you. Please enter your bank account number again.</Say>
_11
</Prompt>
_11
</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.
Use <Prompt> with requireMatchingInputs and errorType
prompt.say('Thanks for using our service. Please enter your bank account number.');
_23
const prompt2 = pay.prompt({
_23
for: 'bank-account-number',
_23
requireMatchingInputs: true
_23
});
_23
prompt2.say('Thank you. Please enter your bank account number again.');
_23
const prompt3 = pay.prompt({
_23
for: 'bank-account-number',
_23
errorType: 'input-matching-failed'
_23
});
_23
prompt3.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>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>
_14
</Prompt>
_14
</Pay>
_14
</Response>
errorType
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.
Example <Prompt> usage
Use <Prompt>s to customize prompts for credit card payments
The following examples show the TwiML you can use to customize all prompts for <Pay> when accepting a credit card payment:
A full example of using <Prompt> for a credit card transaction
prompt.say('Please enter your credit card number.');
_89
const prompt2 = pay.prompt({
_89
for: 'payment-card-number',
_89
errorType: 'timeout'
_89
});
_89
prompt2.say('You didn\'t enter your credit card number. Please enter your credit card number.');
_89
const prompt3 = pay.prompt({
_89
for: 'payment-card-number',
_89
errorType: 'invalid-card-number'
_89
});
_89
prompt3.say('You entered an invalid credit card number. Please try again.');
_89
const prompt4 = pay.prompt({
_89
for: 'payment-card-number',
_89
errorType: 'invalid-card-type'
_89
});
_89
prompt4.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.');
_89
const prompt5 = pay.prompt({
_89
for: 'expiration-date'
_89
});
_89
prompt5.say('Please enter your credit card\'s expiration date. Two digits for the month and two digits for the year.');
_89
const prompt6 = pay.prompt({
_89
for: 'expiration-date',
_89
errorType: 'timeout'
_89
});
_89
prompt6.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.');
_89
const prompt7 = pay.prompt({
_89
for: 'expiration-date',
_89
errorType: 'invalid-date'
_89
});
_89
prompt7.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.');
_89
const prompt8 = pay.prompt({
_89
for: 'security-code',
_89
cardType: 'visa mastercard'
_89
});
_89
prompt8.say('Please enter your security code. It\'s the 3 digits located on the back of your card.');
_89
const prompt9 = pay.prompt({
_89
for: 'security-code',
_89
errorType: 'timeout',
_89
cardType: 'visa mastercard'
_89
});
_89
prompt9.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.');
_89
const prompt10 = pay.prompt({
_89
for: 'security-code',
_89
errorType: 'invalid-security-code',
_89
cardType: 'visa mastercard'
_89
});
_89
prompt10.say('That was an invalid security code. The security code must be 3 digits. Please try again.');
_89
const prompt11 = pay.prompt({
_89
for: 'security-code',
_89
cardType: 'amex'
_89
});
_89
prompt11.say('Please enter your security code. It\'s the 4 digits located on the front of your card.');
_89
const prompt12 = pay.prompt({
_89
for: 'security-code',
_89
errorType: 'timeout',
_89
cardType: 'amex'
_89
});
_89
prompt12.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.');
_89
const prompt13 = pay.prompt({
_89
for: 'security-code',
_89
errorType: 'invalid-security-code',
_89
cardType: 'amex'
_89
});
_89
prompt13.say('That was an invalid security code. The security code must be 4 digits. Please try again.');
_89
const prompt14 = pay.prompt({
_89
for: 'postal-code'
_89
});
_89
prompt14.say('Please enter your 5 digit billing zip code.');
_89
const prompt15 = pay.prompt({
_89
for: 'postal-code',
_89
errorType: 'timeout'
_89
});
_89
prompt15.say('You didn\'t enter your billing zip code. Please enter your 5 digit billing zip code.');
_89
const prompt16 = pay.prompt({
_89
for: 'payment-processing'
_89
});
_89
prompt16.say('Thank you. Please wait while we process your payment.');
<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>
_59
</Prompt>
_59
<!-- Prompts for expiration date -->
_59
<Prompt for="expiration-date">
_59
<Say>Please enter your credit card's expiration date. Two digits for the month and two digits for the year.</Say>
<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>