TwiML™ Voice: <Pay>

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

A list of inputs that Twilio should accept for <Pay>. It supports dtmf only.

<Pay> redacts all digits captured from the logs.

Back to attributes list

The URL where Twilio will send a POST request for the next set of TwiML instructions after a successful <Pay> transaction.

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 the action URL. The body of the request includes the standard request parameters and the additional parameters described in the Twilio's POST request to your action URL section below.

Twilio's default action makes a POST request to the current document URL.

The attribute only accepts https protocol for the URL.

If you made a tokenize transaction, Twilio's request to your application includes the PaymentToken parameter, the ProfileId parameter, or both. These fields contain the tokenized information received from the Payment Gateway.

If you made a charge transaction, Twilio's request to your application will include a PaymentConfirmationCode parameter with the confirmation code received from the payment processor or gateway.

After a successful <Pay> transaction, Twilio will send a POST request to your action URL. The body of this request will contain the standard request parameters, along with the additional parameters listed in the following table.

The Result property contains the result of the <Pay> transaction. The following table lists possible values.

The ProfileId property identifies the customer object associated with the payment. You can use this property as a token depending on which Pay Connector, payment processor, or both that you used.

• ACI: no value
• Base Commerce: no value
• Braintree: ID of the customer object (can't use as a token)
• CardConnect: profile
• Chase: customer reference number
• Stripe: ID of the customer resource

The PaymentToken property is the tokenized value of the credit card or ACH payment data. Each payment processor handles tokens in their own way. The following list offers some examples.

• ACI uses a Card Token.
• Base Commerce uses a BankCard Token.
• Braintree and CardConnect use a token.
• Chase doesn't use tokens.
• Stripe can return one of two types of tokenized data:
  • If your request set the tokenType attribute to one-time or reusable, the response returns a Token object id .
  • If your request set the tokenType attribute to payment-method, the response returns a PaymentMethod object id.

If the request used <Pay> to process the payment instead of tokenizing, the PaymentConfirmationCode property returns confirmation code from the payment gateway.

This property indicates the payment method that the developer set in the <Pay> verb's paymentMethod attribute. Possible values are ach-debit and credit-card.

If your request set paymentMethod="credit-card", the response includes the card number that the caller or consumer provided with only last 4 digits visible. Example value: "xxxx-xxxxxx-x4001"

If your request set paymentMethod="credit-card", the response includes the type of card that the caller or consumer provided. The value will be one of the validCardTypes:

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

If your request set paymentMethod="credit-card", the response includes the expiration date that the caller or consumer provided in MMYY (two-digit month, two-digit year) format. Example value: 0522

If your request set paymentMethod="credit-card", the response includes the security code that the caller or consumer provided. Twilio redacts this value in the response. Example value: ***

If your request set paymentMethod="credit-card", the response includes the postal code that the caller or consumer provided. Example value: 94109

If your request set paymentMethod="ach-debit", the response includes the bank account number that the caller or consumer provided. Twilio redacts all but the last 2 digits of this value in the response. Example: A customer enters 508862392. The BankAccountNumber value will be *******92

If your request set paymentMethod="ach-debit", the response includes the complete bank routing number that the caller or consumer provided. Example value: 121181976

If your request set paymentMethod="ach-debit", the response includes the type of bank account that the caller or consumer provided. Possible values include, but not limited to, "personal" or "business".

The PaymentError property shows error details for the following types of errors:

• Validation error for incorrect <Pay> verb attribute.
  • Example value: paymentAmount='-0.59' (not a number between 0.00 - 1,000,000.00)
• Payment error for failures.
  • Example value: card is declined
• Payment error for input timeout.
  • Example value: invalid-date (if user enters an invalid date or incorrect number of digits and times out)
  • Example value: invalid-security-code (if user enters an invalid CVV and times out)
  • Example value: invalid-postal-code (if user enters incorrect number of alphanumeric characters for the postal code and times out)

The PayErrorCode property is a numerical error code that gives more details about the error. To learn more about the error, visit the Error Code Dictionary and search for the error code.

The ConnectorError property contains the actual error code/message received from the underlying payment platform.

Back to attributes list

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

The unique identifier of the Twilio Account responsible for this Pay session

A unique identifier for the Call Resource associated with the Pay sessions. CallSid always refers to the parent leg of a two-leg call.

The current stage of <Pay> request. The following table describes the possible values.

The type of error that occurred (if applicable). The following table describes the possible error types.

The Attempt property indicates the current attempt count.

Possible values are 1, 2, or 3.

For ach-debit payments only.

The PaymentCardNumber indicates the card number provided to <Pay> with only the last 4 digits visible. For example: "xxxxxxxxxxx4001"

For credit-card payments only.

The PaymentCardType indicates the type of card provided to <Pay>, For example: "amex" The value provided here will be one of the values provided in the validCardTypes attribute.

For credit-card payments only.

The ExpirationDate contains the credit card expiration date provided to <Pay> in MMYY (two-digit month, two-digit year) format. You would write a May 2022 expiration date as "0522" Note: The response displays this date in plaintext as it isn't PCI data.

For credit-card payments only.

The SecurityCode contains the security code for the credit card provided to <Pay>. The response returns this value with all digits redacted.

For credit-card payments only.

The PaymentCardPostalCode contains the postal code that the caller or consumer provided. For example: "94109" Note: The response displays this value in plaintext as it isn't PCI data.

For ach-debit payments only.

The BankAccountNumber contains the bank account number that the caller or consumer provided. Twilio returns all but last two digits of this value redacted. For example: "*******92".

For ach-debit payments only.

The BankRoutingNumber contains the complete bank routing number that the caller or consumer provided. For example: "121181976"

For ach-debit payments only.

The BankAccountType contains the bank account type that the caller or consumer provided. Possible values are:

• consumer-checking
• consumer-savings
• commercial-checking

Back to attributes list

The paymentMethod attribute specifies 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).

To capture bank account information, set the value of the paymentMethod attribute to "ach-debit" as shown below.

1
<Response>
2
   <Pay paymentConnector=”Your_Connector_Name” paymentMethod=”ach-debit” />
3
</Response>
4

Once <Pay> successfully captures the information, it will securely send that information to the appropriate payment platform using the Pay Connector you've configured. Twilio returns the results from the payment platform via a webhook to the action URL specified in the <Pay> verb.

Back to attributes list

This attribute indicates the type of bank account information is being that the caller or consumer provided when capturing ACH payments. The bankAccountType attribute accepts either "consumer-checking","consumer-savings", "commercial-checking".

The processing speed of the ACH transactions depends on the bankAccountType and the underlying payment platform used.

Use <Gather> to capture the type of bank account and pass one of the allowed values to your bankAccountType attribute when using <Pay> to capture ACH payments.

Back to attributes list

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 account or routing numbers.

Back to attributes list

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

The default of 1 means <Pay> retries once when it encounters a timeout or receives invalid data. For example, if it receives a timeout when prompted for credit card number, <Pay> reprompts one more time to enter credit card number before terminating. When <Pay> hits the maxAttempts value, <Pay> terminate and TwiML execution starts with next verb after <Pay>.

Back to attributes list

To let <Pay> know whether to prompt for security code, set the securityCode attribute to true or false .

When you set paymentMethod to credit-card, <Pay> collects the credit card number, expiration date, security code and zip code. Use <Pay securityCode=”false” /> to disable prompting for security code.

Back to attributes list

To let <Pay> know whether to prompt for a postal code, like the U.S. ZIP code, set the postalCode attribute to true or false.

When paymentMethod="credit-card", <Pay> collects credit card number, expiration date, security code and postal code. To disable prompting for postal code, use <Pay postalCode=”false” />. If you have access to customer code, provide the postal code as value to the attribute. For example, if the billing postal code is 95105 then use <Pay postalCode=”94105” />. When processing this payment, <Pay> passes 94105 to the Payment Gateway.

Back to attributes list

The minPostalCodeLength attribute takes a positive integer to let <Pay> validate the length of the postalCode attribute. Twilio expects users to enter at least these many alphanumeric characters.

Back to attributes list

The chargeAmount attribute takes an amount to charge against the credit card or bank account that <Pay> captured. 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 $20.45.

To override the default currency, use the currency attribute.

Back to attributes list

The currency attribute provides the currency of the amount attribute. This attribute defaults to usd (US Dollars). It accepts all values that the selected Pay Connector accepts.

Back to attributes list

The language attribute provides the language that a customer hears when interacting with <Pay>.

For credit card payments, possible values are:

• English:

  • en-AU
  • en-CA
  • en-GB
  • en-IN
  • en-US

• Spanish:

  • es-ES
  • es-MX

• French:

  • fr-CA
  • fr-FR

• German:

  • de-DE

• Italian:

  • it-IT

For ACH, possible values are:

• English:

  • en-AU
  • en-CA
  • en-GB
  • en-IN
  • en-US

You can also further customize what the customer hears using the <Prompt> noun.

Back to attributes list

The paymentConnector attribute must contain the unique name corresponding to the Pay Connector installed in your Twilio Marketplace Account in the Twilio Console. Learn more on the Pay Connectors page.

For example, to process the transaction using Stripe use paymentConnector=Stripe_1, where Stripe_1 is the unique name specified when configuring the Pay Connector Add-on in the Marketplace.

If no one specifies a paymentConnector, <Pay> uses the Pay Connector on your account with the unique name "Default".

If you are using a Generic Pay Connector, you can use the <Parameter> noun with <Pay> to pass custom parameters to your payment processor.

Back to attributes list

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

If you're using a Stripe Pay Connector, payment-method is also a possible value.

Back to attributes list

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

Requests submit this information with the payment details to the Payment Gateway. This data gets 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.

Back to attributes list

The validCardTypes attribute takes credit card types that <Pay> should accept. Separate multiple values with a space.

If the payee enters a card number outside of valid card types, <Pay> returns an "invalid-card-type" error. For example, if validCardTypes=visa mastercard and payee enters an American Express card number, then <Pay> generates an "invalid-card-type" error.

The default value of validCardTypes is “visa mastercard amex”.

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

Back to attributes list

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

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
response.say('Calling Twilio Pay');
6
response.pay({
7
    chargeAmount: '20.45'
8
});
9

10
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Say>Calling Twilio Pay</Say>   
4
  <Pay chargeAmount="20.45"/>
5
</Response>

Collect payment of a specific amount and specify a callback handler

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3

4
const response = new VoiceResponse();
5
response.say('Calling Twilio Pay');
6
response.pay({
7
    chargeAmount: '20.45',
8
    action: 'https://enter-your-callback-function-url.twil.io/pay'
9
});
10

11
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Say>Calling Twilio Pay</Say>
4
  <Pay chargeAmount="20.45" 
5
    action="https://enter-your-callback-function-url.twil.io/pay"/>
6
</Response>

1
const VoiceResponse = require('twilio').twiml.VoiceResponse;
2

3
const response = new VoiceResponse();
4
response.pay({tokenType: 'one-time', chargeAmount: '0'});
5

6
console.log(response.toString());

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
    <Pay tokenType="one-time" chargeAmount="0" />
4
</Response>