Menu

Expand
Rate this page:

TwiML™ Voice: <Prompt>

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.

Loading Code Sample...
        
        
        Ask for a user's credit card number.

        Prompt for card number

        Ask for a user's credit card number.

        The following TwiML example causes the caller to hear a pre-recorded audio file during the payment-card-number payment step.

        Loading Code Sample...
              
              
              Ask for a user's credit card number through a recorded MP3.

              Prompt for card number with MP3

              Ask for a user's credit card number through a recorded MP3.

              <Prompt> Attributes

              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

              • payment-card-number
              • expiration-date
              • security-code
              • postal-code
              • bank-routing-number
              • bank-account-number
              • payment-processing
              none

              cardType

              optional

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

              Multiple values are allowed and must be space delimited.

              Example: visa amex mastercard

              none

              attempt

              optional

              An integer from 1-10 none

              requireMatchingInputs

              optional

              • true
              • false
              false

              errorType

              optional

              • timeout
              • invalid-card-number
              • invalid-card-type
              • invalid-date
              • invalid-security-code
              • invalid-bank-routing-number
              • invalid-bank-account-number
              • input-matching-failed

              Multiple values are allowed and must be space delimited.

              Example: timeout invalid-bank-account-number invalid-date

              none

              for

              <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

              cardType

              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.

              Loading Code Sample...
                    
                    

                    Prompt for a Visa security code (3 digits)

                    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.

                    Loading Code Sample...
                          
                          

                          Prompt for an American Express security code (4 digits)

                          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.

                          Loading Code Sample...
                                
                                

                                Change prompt for subsequent attempts

                                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.

                                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.

                                Loading Code Sample...
                                      
                                      

                                      Require caller to enter bank account information twice

                                      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.

                                      Loading Code Sample...
                                            
                                            

                                            Use <Prompt> with requireMatchingInputs and errorType

                                            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:

                                            Loading Code Sample...
                                                  
                                                  

                                                  A full example of using <Prompt> for a credit card transaction

                                                  Use <Prompt>s to customize prompts for ACH payments

                                                  The following examples show the TwiML you can use to customize all prompts for <Pay> when accepting an ACH payment:

                                                  Loading Code Sample...
                                                        
                                                        

                                                        A full example of using <Prompt> for an ACH/debit transaction

                                                        Rate this page:

                                                        Need some help?

                                                        We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

                                                        Loading Code Sample...
                                                              
                                                              
                                                              

                                                              Thank you for your feedback!

                                                              Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                                                              Sending your feedback...
                                                              🎉 Thank you for your feedback!
                                                              Something went wrong. Please try again.

                                                              Thanks for your feedback!

                                                              thanks-feedback-gif