メニュー

Expand
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 both ACH and 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 or ACH 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
        paymentMethod (new) credit-card, ach-debit credit-card
        bankAccountType (new) consumer-checking,
        consumer-savings,
        commercial-checking
        consumer-checking
        Timeout Positive integer 5 秒
        maxAttempts Positive integer (max: 3) none
        securityCode true,false true
        postalCode true, false, String true
        minPostalCodeLength (new)

        Positive integer

        none
        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 and/or ProfileId parameter. They contain 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.
        ProfileId

        The identifier of the customer object to which the payment is associated. Can be used as a token depending on the Connector.

        Values:

        ACI - no value

        Base Commerce - no value

        Braintree - ID of the customer object (cannot be used as a token)

        CardConnect - profile

        Chase - customer reference number

        Stripe - ID of the customer resource

        PaymentToken

        The tokenized value of the credit card or ach payment data.

        Values:

        ACI - Card Token

        Base Commerce - BankCard Token

        Braintree - Token

        CardConnect - Token

        Chase - no value

        Stripe - no value

        PaymentConfirmationCode If <Pay> was used to process the payment instead of tokenizing, confirmation code from the Payment Gateway will be available here.
        PaymentMethod The value of the payment method provided by the developer when calling <Pay>. For example, PaymentMethod=ach-debit
        PaymentCardNumber If credit-card paymentMethod used, the card number provided to <Pay> with only last 4 digits visible. For example, PaymentCardNumber=xxxx-xxxxxx-x4001
        PaymentCardType

        If credit-card paymentMethod used,

        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 If credit-card paymentMethod used, The expiration date provided to <Pay> in format MMDD. For example, ExpirationDate=0522
        SecurityCode If credit-card paymentMethod used, The security code provided to <Pay> (with all digits redacted). For example, SecurityCode=xxxx
        PaymentCardPostalCode If credit-card paymentMethod used, the postal code provided to <Pay>. For example, PaymentCardPostalCode=94109
        BankAccountNumber (new) If ach-debit paymentMethod used, the Bank Account Number provided by the caller/consumer. <Pay> will only return the last 2 digits. For example, if the Bank Account Number is 508862392, then <Pay> will return BankAccountNumber=*******92
        BankRoutingNumber (new) If ach-debit paymentMethod used, The Bank Routing Number provided by the caller/consumer. <Pay> will return the full routing number provided by the caller/consumer. For example, if caller enters 121181976 as their Bank Routing Number provided, then <Pay> will return BankRoutingNumber=121181976
        BankAccountType (new) If ach-debit paymentMethod used, The Bank Account Type provided by the caller/consumer. <Pay> will return either personal or business based on caller/consumer input.
        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.

        PayErrorCode

        A numerical error code that gives more details about the error. To learn more about the error, please visit https://www.twilio.com/docs/api/errors and search for the error code.

        ConnectorError

        This parameter contains the actual error code/message received from the underlying payment platform.

        Result Values

        The following are the possible values for the Result parameter.

        result 概要
        success <Pay> successfully captured the payment data and either tokenized or processed the payment.
        too-many-failed-attempts Max attempts reached when capturing the payment 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 If credit-card paymentMethod used, the card number provided to <Pay> with only last 4 digits visible. For example, PaymentCardNumber=xxxx-xxxxxx-x4001
        PaymentCardType

        If credit-card paymentMethod used,

        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

        If credit-card paymentMethod used, the expiration date provided to <Pay>. For example, ExpirationDate=0522

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

        SecurityCode If credit-card paymentMethod used, the security code provided to <Pay> with all digits redacted. For example, SecurityCode=xxxx
        PaymentCardPostalCode

        If credit-card paymentMethod used, the postal code provided to <Pay>. For example, PaymentCardPostalCode=94109

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

        BankAccountNumber (new)

        if ach-debit paymentMethod used, the Bank Account Number provided by the caller/consumer.

        <Pay> will only return the last 2 digits. For example, if the Bank Account Number is 508862392, then <Pay> will return BankAccountNumber=*******92

        BankRoutingNumber (new)

        if ach-debit paymentMethod used, The Bank Routing Number provided by the caller/consumer.

        <Pay> will return the full routing number provided by the caller/consumer. For example, if caller enters 121181976 as their Bank Routing Number provided, then <Pay> will return BankRoutingNumber=121181976

        BankAccountType (new)

        if ach-debit paymentMethod used, The Bank Account Type provided by the caller/consumer.

        <Pay> will return either personal or business based on caller/consumer input.

        paymentMethod

        The paymentMethod attribute specifiies whether to capture Credit Card or ACH payment information.

        <Pay> by default captures credit card information (credit card number, expiration date, security code, and postal code). Return the following TwiML to instruct <Pay> to capture Bank Account information.

        <Response>
           <Pay paymentConnector=”Your Connector Name” paymentMethod=”ach-debit” />
        </Response>
        

        Once <Pay> successfully captures the information, it will securely send that information to appropriate payment platform using the connector configured by customer and returns the results from payment platform via webhook to <Pay> action url.

        bankAccountType

        The bankAccountType attribute accepts either consumer checking, consumer savings, commercial checking.

        When using <Pay> to capture ACH payments, it is required to pass whether the bank account information being provided is for personal checking, personal savings or commercial checking. The speed at which the ACH transactions are processed depends on the type of Bank Account Type and the underlying payment platform used. Customers should use <Gather> to capture the type of bank account and pass one off allowed values when using <Pay> to capture ACH payments.

        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. When accepting ACH payments, <Pay> will wait three seconds for the caller to press a key when capturing either bank accounting or routing numbers.

        securityCode

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

        When paymentMethod is credit card, <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).

        When paymentMethod is credit card, <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.

        minPostalCodeLength

        The minPostalCodeLength attribute takes a positive integer to let <Pay> validate the length of the postalCode attribute. Users are expected to enter atleast these many digits.

        chargeAmount

        The chargeAmount attribute takes an amount to charge against the credit card or bank account captured by <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 accept all values accepted by the selected Payment Connector

        language

        The laguage attribute is used to provide the language that a customer hears when interacting with <Pay>. For credit card payments, it accepts languages with tags de, en, es and fr. For ACH, it accepts languages with tags en.

        paymentConnector

        The paymentConnector attribute must contain the unique name corresponding to the Payment Gateway Connector installed in the Twilio Add-ons. Learn more about <Pay> Connectors here.

        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-19 digits. *

        The digits must begin with 300, 301, 302, 303, 304, 3095, 36, 38, or 39.

        * Note: In the case that digits begin with 36, valid length is 14-19 digits.

        enroute

        Valid length: 15 digits.

        First four digits must be 2014 or 2149.

        <Parameter> Noun

        The <Parameter> noun is a subelement within the <Pay> verb. This noun, <Parameter>, is required when accepting ACH payments in order to capture certain ACH information not included as part of the <Pay> verb to send to the payment provider. The value(s) that have to be captured by <Parameter> depend on the payment provider.

        <Pay chargeAmount="10.0" description="pizza" paymentMethod="ach-debit" paymentConnector="myConnector" action="myactionurl">
          <Parameter name="AVSName" value="CallerABC"/>
        </Pay>
        

        <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.
                    Rate this page:

                    ヘルプが必要ですか?

                    誰しもが一度は考える「コーディングって難しい」。そんな時は、お問い合わせフォームから質問してください。 または、Stack Overflow でTwilioタグのついた情報から欲しいものを探してみましょう。