メニュー

Rate this page:

Thanks for rating this page!

We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

TwiML™ Voice: <Pay>

You can use TwiML's <Pay> verb to capture and process credit card data during a call.

The following example shows the most basic use of <Pay>:

        
        
        
        
        Collect payment during a voice call.

        Basic Pay TwiML Usage

        Collect payment during a voice call.

        In addition to managing necessary interactions when there is timeout or invalid input <Pay> will generate webhooks to a statusCallback URL to keep you informed of the progress of <Pay>. Once all required credit card data is captured, <Pay> will either tokenize or create a charge using a <Pay> Connector installed and configured on your account.

        <Pay> will terminate when DTMF * is received at any point and immediately webhook to the action Url. Twilio will continue the current call using the TwiML returned in the webhook response.

        <Pay> Attributes

        The <Pay> verb supports the following attributes to modify its default behavior:

        属性名 許容値 Default Values
        input DTMF DTMF
        action 相対または絶対 URL Current document URL. Must use https. Only POST is supported.
        statusCallback 相対または絶対 URL none
        Timeout Positive integer 5 秒
        maxAttempts Positive integer (Max 3)
        securityCode true,false true
        postalCode true, false, String true
        paymentConnector 文字列 初期値
        tokenType String (one-time, reusable) reusable
        chargeAmount Positive Decimal (min: 1.00, max: 1,000,000) none
        currency 文字列 usd
        description 文字列 none
        validCardTypes

        visa

        mastercard

        amex

        maestro

        discover

        optima

        jcb

        diners-club

        enroute

        visa mastercard amex

        input

        A list of inputs that Twilio should accept for <Pay>; only dtmf is supported. All the digits captured by <Pay> are redacted from the logs.

        action

        The action attribute takes an absolute or relative URL as value. When the <Pay> verb has successfully tokenized or created a charge, Twilio will make a POST request to this URL including the standard request parameters as well as additional parameters described below. If no action is provided, Twilio will by default make a POST request to the current document URL. The attribute only accepts https protocol for the URL.

        If you chose to tokenize the information, Twilio's request to your application will include the PaymentToken parameter. It contains the tokenized information received from the Payment Gateway. If you chose to create a charge, then Twilio’s request to your application will include PaymentConfirmationCode parameter with the confirmation code received from the Payment Gateway.

        Additional Request Parameters

        <Pay> will post the following additional parameters in addition to the standard request parameters.

        パラメーター 概要
        Result The result of <Pay>. See the table below for all the values.
        PaymentToken The tokenized value of the credit card data
        PaymentConfirmationCode If <Pay> was used to process the payment instead of tokenizing, confirmation code from the Payment Gateway will be available here.
        PaymentCardNumber The card number provided to <Pay> with only last 4 digits visible. For example, PaymentCardNumber=xxxx-xxxxxx-x4001
        PaymentCardType

        The type of card provided to <Pay>. For example, PaymentCardType=amex

        The value provided here will be one of the values provided with cardTypes attribute in <Pay>.

        ExpirationDate The expiration date provided to <Pay> in format MMDD. For example, ExpirationDate=0522
        SecurityCode The security code provided to <Pay> (with all digits redacted). For example, SecurityCode=xxxx
        PaymentCardPostalCode The postal code provided to <Pay>. For example, PaymentCardPostalCode=94109
        PaymentError

        Validation error for incorrect <Pay> verb attribute. For example, paymentAmount=”-0.59” (not a number between 0.00 - 1,000,000.00)

        Payment error for failures. For example, card is declined.

        Result Values

        The following are the possible values for the Result parameter.

        Result 概要
        success <Pay> successfully captured the credit card data and either tokenized or processed the payment.
        too-many-failed-attempts Max attempts reached when capturing the credit card data.
        payment-connector-error <Pay> experienced an error communicating with Payment Gateway.
        caller-interrupted-with-star Caller pressed * (star) key to interrupt <Pay>
        caller-hung-up Caller hung-up the call.
        validation-error Invalid <Pay> verb attribute e.g. paymentAmount=”-0.5”
        internal-error

        statusCallback

        The statusCallback attribute takes an absolute or relative Url as value. Whenever a status change happens in <Pay>, Twilio will make a POST request to this URL with the following parameters.

        パラメーター

        <Pay> will POST the following parameters to the statusCallback url:

        パラメーター 概要
        AccountSid この録音の属するアカウントの一意な識別子です。
        CallSid A unique identifier for the call associated with the recording. CallSid will always refer to the parent leg of a two-leg call.
        アカウント The current stage of <Pay>. The full list is available here.
        ErrorType The full list of Error Type is visible here.
        Attempt The current attempt count. For example, Attempt=1
        PaymentCardNumber The card number provided to <Pay> with only last 4 digits visible. For example, PaymentCardNumber=xxxx-xxxxxx-x4001
        PaymentCardType

        The type of card provided to <Pay>. For example, PaymentCardType=amex

        The value provided here will be one of the values provided with cardTypes attribute in <Pay>.

        ExpirationDate

        The expiration date provided to <Pay>. For example, ExpirationDate=0522

        Note: Expiration date is not PCI data, so it can be clearly visible.

        SecurityCode The security code provided to <Pay> with all digits redacted. For example, SecurityCode=xxxx
        PaymentCardPostalCode

        The postal code provided to <Pay>. For example, PaymentCardPostalCode=94109

        Note: Postal Code is not PCI data, so it can be clearly visible.

        maxAttempts

        The maxAttempts attribute specifies number of times <Pay> should retry when collecting information.

        The default is 1 which means <Pay> will retry once when a timeout or invalid value is received. For example, if a timeout is received when prompted for credit card number, <Pay> will reprompt one more time to enter credit card number before terminating. When <Pay> hits the maxAttempts value, <Pay> will terminate and TwiML execution will start with next verb after <Pay>.

        Timeout

        The timeout attribute sets the limit in seconds that <Pay> will wait for the caller to press another digit before moving on to validate the digits captured.

        For example, if timeout is 3, <Pay> will wait three seconds for the caller to press a key when capturing either credit card number, expiration date, security code or zip code.

        securityCode

        The securityCode attribute takes true or false to let <Pay> know whether to prompt for security code.

        <Pay> by default will collect credit card number, expiration date, security code and zip code. Use <Pay securityCode=”false” /> to disable prompting for security code.

        postalCode

        The postalCode attribute takes true or false to let <Pay> know whether to prompt for postal code (i.e zip code).

        <Pay> by default will collect credit card number, expiration date, security code and postal code (Zip code in US). Use <Pay postalCode=”false” /> to disable prompting for postal code. In addition, if you already have access to customer code instead of asking the payee for that information provide the postal code as value to the attribute. For example, if the billing postal code is 95105 then use <Pay postalCode=”94105” /> and <Pay> will pass 94105 to the Payment Gateway when processing the payment.

        chargeAmount

        The chargeAmount attribute takes an amount to charge against the credit card captured <Pay>. If the charge amount attribute has a value > 0, then <Pay> will request the payment connector you chose to create a charge on the card instead of tokenizing. The attribute takes a decimal value with no currency prefix and defaults to USD. For example, use chargeAmount=20.45 to process payment in the amount of twenty five dollars and forty five cents. The default currency can be override with currency attribute.

        currency

        The currency attribute is used to provide the currency of the amount attribute. The default value for currency is usd and supports the following values,

        Currency 概要
        usd US Dollar
        cad Canadian Dollar
        eur Euro
        gbp British Pound

        paymentConnector

        The paymentConnector attribute must contain the unique name corresponding to the Payment Gateway Connector installed in the Twilio Add-ons.

        For example, to process the transaction using Stripe use paymentConnector=Stripe_1, where Stripe_1 is the unique name specified when configuring the Payment Gateway Connector Add-on in the Marketplace. This is a mandatory attribute.

        tokenType

        The tokenType attribute takes either one-time or reusable as value.

        If <Pay> should generate a one time token, use tokenType=one-time and to generate a token for recurring payments use, tokenType=reusable.

        description

        The description attribute takes a value that describes more details regarding the payment.

        This information is submitted along with the payment details to the Payment Gateway which are then posted on the transactions. For example, you can provide “Payment of $20.52 submitted from CallSid CAxxxxxx and Phone Number (xxx)-xxx-xxxx” to create a record to show which call created the payment.

        validCardTypes

        The validCardTypes attributes takes credit card types separated by space that <Pay> should accept.

        If payee enters a card number that is outside of valid card types, <Pay> will generate “invalid-card-type” error. For example, if validCardTypes=visa master-card and payee enters Amex, then <Pay> will generate error invalid-card-type. The attribute defaults to “Visa MasterCard Amex”.

        A customer could provide any of the following card types separated by space:

        Card Type 概要
        visa Valid length: 13, 15, 19 digits. First digit must be a 4.
        mastercard

        Valid length: 16 digits.

        First digit must be 5 and second digit must be in the range 1 through 5 inclusive. The range is 510000 through 559999.

        First digit must be 2 and second digit must be in the range 2 through 7 inclusive. The range is 222100 through 272099.

        amex Valid length: 15 digits. First digit must be a 3 and second digit must be a 4 or 7.
        maestro

        Valid length: 12-19 digits.

        First digit must be either 5 or 6.

        If the first digit starts with 5, then second digit must be either 0, 6, 7 or 8.

        discover

        Valid length: 16-19 digits.

        Must start with either 64, 65 or 6011

        jcb

        Valid length: 16 to 19 digits.

        First 4 digits must be in the range 3528 through 3589.

        diners-club

        Diners Club for USA & Canada

        Valid length: 16 digits.

        The first two digits must be 54 or 55

        enroute

        Valid length: 15 digits.

        First four digits must be 2014 or 2149.

        <Pay> Sample Usage

        Collect payment data during a voice call and charge a specific amount.

              
              
              
              
              Charge a specific amount and collect payment.

              Collect payment for a specific amount

              Charge a specific amount and collect payment.

              Collect payment of a specific amount and specify a callback handler

                    
                    
                    
                    
                    Capture payment details, charge a specific amount, and set a callback URL.

                    Receive a callback on payment actions

                    Capture payment details, charge a specific amount, and set a callback URL.

                    ヘルプが必要ですか?

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