<Pay> and the Payment resource are now available in the Ireland (IE1) and Australia (AU1) Regions for the following Pay Connectors: Base Commerce, Braintree, CardConnect, Chase Paymentech, Generic Pay Connector, and Shuttle.
You can use TwiML's <Pay>
verb to capture and process both ACH and credit card data during a call.
<Pay>
will prompt your customer to enter their payment information and will handle retries if a piece of information is invalid.
In addition to managing necessary interactions when there is timeout or invalid input, <Pay>
will send webhooks to your statusCallback
URL to keep you informed of the progress of <Pay>
.
Once all required credit card or ACH data is captured, <Pay>
will send the payment information to your payment processor or gateway via a Pay Connector installed and configured on your account.
Once <Pay>
finishes collecting a customer's valid payment information, information about the transaction result will be sent via webhook to your statusCallback
URL and/or your action
URL.
<Pay>
will terminate when DTMF *
keypress is received at any point.
When <Pay>
finishes collecting a customer's valid payment information or is terminated with a *
keypress, Twilio will immediately send a webhook (an HTTP POST
request) to the action
URL.
Twilio will continue the current call using the TwiML returned in the response from the action
URL.
<Pay>
can create two types of transactions: charge and tokenize.
A charge transaction means you want to immediately capture funds from the customer's supplied payment method (i.e. credit card) in return for the goods or services you offer.
chargeAmount
attribute in your
<Pay>
verb to a decimal value greater than 0.
A tokenize transaction means you want to obtain a token based on the user's supplied credit card information from the payment processor instead of posting any charge. Tokens are typically stored so that you can charge the user in the future without having to ask for the credit card information again. Note that tokens are provided by your payment gateway or processor.
chargeAmount
to "0"
or
omit the
chargeAmount
attribute from your
<Pay>
verb.
The <Pay>
verb supports the following attributes to modify its default behavior:
Attribute | Allowed values | Default values |
---|---|---|
input | dtmf | dtmf |
action | A relative or absolute URL | Current document URL. Must use https. Only POST is supported. |
statusCallback | A relative or absolute URL | none |
paymentMethod | ach-debit , credit-card | credit-card |
bankAccountType | consumer-checking , consumer-savings , commercial-checking | consumer-checking |
timeout | A positive integer | 5 |
maxAttempts | 1 , 2 , 3 | none |
securityCode | true , false | "true" |
postalCode | true , false , a String value | "true" |
minPostalCodeLength | A positive integer | none |
paymentConnector | A String value | Default |
tokenType | one-time ,reusable , payment-method | reusable |
chargeAmount | A decimal (min: 0, max: 1,000,000) | none |
currency | A String value | usd |
language | See list in the language section below. | en-us |
description | A String value | none |
validCardTypes | One or more of the following values: visa , mastercard , amex , maestro , discover , optima , jcb , diners-club , enroute | "visa mastercard amex" |
A list of inputs that Twilio should accept for <Pay>
; only dtmf is supported.
All digits captured by <Pay>
are redacted from the logs.
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.
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 made a tokenize transaction, Twilio's request to your application will include the PaymentToken
and/or ProfileId
parameter. 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/gateway.
If you started or updated a call with a twiml
parameter, the action
URLs for <Record>
, <Gather>
, and <Pay>
must be absolute.
The Call Resource API Docs have language-specific examples of creating and updating Calls with TwiML:
twiml
parameter.
twiml
parameter.
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 table below.
The Result
property is the result of the <Pay>
transaction. Possible values are listed in the table below.
Result value | Description |
---|---|
success | Twilio successfully captured the payment data and either tokenized or processed the payment |
too-many-failed-attempts | Max attempts reached when capturing the payment information |
payment-connector-error | Twilio experienced an error communicating with the payment processor or gateway |
caller-interrupted-with-star | Caller pressed * (star) key to interrupt the payment session |
caller-hung-up | Caller hung up the call |
validation-error | Invalid <Pay> verb attribute (e.g. paymentAmount="-0.5") |
iternal-error | Twilio encountered an error |
The ProfileId
property is the identifier of the customer object to which the payment is associated. Can be used as a token depending on which Pay Connector and/or payment processor used.
The PaymentToken
property is the tokenized value of the credit card or ACH payment data. Each payment processor handles this differently:
tokenType
is
one-time
or
reusable
.
tokenType
is
payment-method
.
The PaymentConfirmationCode
property indicates if <Pay>
was used to process the payment instead of tokenizing, this is the confirmation code from the payment gateway.
The PaymentMethod
property indicates the payment method provided by the developer in the <Pay>
verb's paymentMethod
attribute. Example value: "ach-debit"
If credit-card
paymentMethod
was used, this is the card number provided by the caller/consumer with only last 4 digits visible. Example value: "xxxx-xxxxxx-x4001"
If credit-card
paymentMethod
was used, the PaymentCardType
property is the type of card provided by the caller/consumer. The value will be one of the validCardTypes
:
visa
mastercard
amex
maestro
discover
optima
jcb
diners-club
enroute
If credit-card
paymentMethod
was used, this is the expiration date provided by the caller/consumer in MMDD (two-digit month, two-digit date) format. Example value: 0522
If credit-card
paymentMethod
was used, this is the security code provided by the caller/consumer. This value will be redacted. Example value: ***
If credit-card
paymentMethod
was used, this is the postal code provided by the calller/consumer. Example value: 94109
If ach-debit
paymentMethod
was used, this is the bank account number provided by the caller/consumer. The value will be redacted except for the last 2 digits. Example: A customer enters 508862392. The BankAccountNumber
value will be *******92
If ach-debit
paymentMethod
was used, this is the bank routing number provided by the caller/consumer. The value will be the full routing number provided by the caller/consumer. Example value: 121181976
If ach-debit
paymentMethod
was used, this is the type of bank account provided by the caller/consumer. Possible values are either "personal"
or "business"
.
The PaymentError
property shows error details for the following types of errors:
<Pay>
verb attribute.
paymentAmount='-0.59' (not a number between 0.00 - 1,000,000.00)
card is declined
invalid-date
(if user enters an invalid date or incorrect number of digits and times out)
invalid-security-code
(if user enters an invalid CVV and times out)
invalid-postal-code
(if user enters incorrect number of digits for the postal/zip 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, please 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.
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.
Twilio will send the following parameters in the body of the POST
request to your statusCallback
URL:
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>
. The possible values are described in the table below.
For value | 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 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 |
The type of error that occurred (if applicable). The possible error types are described in the table below.
ErrorType value | Description |
---|---|
input-timeout | The payment session experienced a timeout at one of the stages of the Pay session. See PaymentError for more details on what field did the caller timed out on. |
invalid-card-number | The card entered did not pass validation. This could include incorrect number of digits for the credit card number, expiration date, security code, or postal code. |
invalid-card-type | The card number didn't match the accepted card types as specified by the validCardTypes attribute |
invalid-date | The date entered was the incorrect number of digits, was in the past, or was otherwise not a valid date |
invalid-security-code | Twilio received an invalid security code |
invalid-postal-code | Twilio didn't receive the correct number of digits for the postal/zip code |
invalid-bank-routing-number | Twilio either didn't receive the correct number of digits for the routing number or the routing number provided failed validation |
invalid-bank-account-number | Twilio didn't receive the minimum number of digits required for the bank account number |
invalid-bank-account-type | Twilio didn't receive the accepted values for BankAccountType field |
invalid-card-number-security-code-capture-sequence | CVV can only be validated against a credit card. If CVV was captured in incorrect sequence i.e. before the credit card number, this error is thrown. |
input-matching-failed | Caller's inputs didn't match when using <Prompt> with requireMatchingInputs . |
session-in-progress | If Twilio receives a request to start a new Pay session, while the existing Pay session is not complete or cancelled, this error is thrown. |
internal-error | Twilio encountered an internal error. |
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. e.g. "xxxxxxxxxxx4001"
For credit-card
payments only.
The PaymentCardType
indicates the type of card provided to <Pay>
, e.g. "amex"
The value provided here will be one of the values provided in the validCardTypes
attribute.
For credit-card
payments only.
The ExpirationDate
is the expiration date provided to <Pay>
in MMDD (two-digit month, two-digit date) format, e.g. "0522"
Note: Expiration date is not PCI data, so it can be clearly visible.
For credit-card
payments only.
The SecurityCode
is the security code provided to <Pay>
with all digits redacted, e.g. "xxxx"
For credit-card
payments only.
The PaymentCardPostalCode
is the postal code provided to <Pay>
, e.g. "94109"
Note: Postal Code is not PCI data, so it can be clearly visible.
For ach-debit
payments only.
The BankAccountNumber
is the bank account number provided by the caller/consumer. Only the last two digits will be unredacted, e.g. "*******92"
.
For ach-debit
payments only.
The BankRoutingNumber
is the bank routing number provided by the caller/consumer. <Pay>
will return the full routing number provided by the caller/consumer, e.g. "121181976"
For ach-debit
payments only.
The BankAccountType
is the bank account type provided by the caller/consumer. Possible values are:
consumer-checking
consumer-savings
commercial-checking
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.
This attribute indicates the type of bank account information is being provided by the caller/consumer when capturing ACH payments. The bankAccountType
attribute accepts either "consumer-checking"
,"consumer-savings"
, "commercial-checking"
.
The speed at which the ACH transactions are processed 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.
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.
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>
.
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.
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.
The minPostalCodeLength
attribute takes a positive integer to let <Pay>
validate the length of the postalCode attribute. Users are expected to enter at least these many digits.
The chargeAmount
attribute takes an amount to charge against the credit card or bank account captured by <Pay>
. The attribute takes a decimal value with no currency prefix and defaults to USD.
If the chargeAmount
attribute has a value greater than 0, the transaction will be a charge transaction.
If the chargeAmount
attribute has a value of 0 or is omitted from the <Pay>
verb, the transaction will be a tokenize transaction.
For example, use chargeAmount="20.45"
to process payment in the amount of $20.45.
The default currency can be overriden with currency attribute.
The currency
attribute is used to provide the currency of the amount attribute. The default value for currency is usd
(US Dollars) and accepts all values accepted by the selected Pay Connector
The language
attribute is used to provide 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.
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 paymentConnector
is specified, <Pay>
will use 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.
You must have an installed Pay Connector named "Default" or you must include the paymentConnector
attribute.
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.
To tokenize a payment method, set chargeAmount
= 0
or omit the chargeAmount
attribute.
If <Pay>
should generate a one-time token, use tokenType="one-time"
and to generate a token for recurring payments use, tokenType="reusable"
.
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.
The validCardTypes
attributes takes credit card types separated by space that <Pay>
should accept.
If the payee enters a card number that is outside of valid card types, <Pay>
will generate an "invalid-card-type" error. For example, if validCardTypes=visa mastercard
and payee enters an American Express card number, then <Pay>
will generate 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:
Card Type | Description |
---|---|
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 US and Canada Valid length: 16-19 digits. * The digits must begin with 300, 301, 302, 303, 304, 3095, 36, 38, or 39. * Note: If first two digits are 36, valid length is 14-19 digits. |
enroute | Valid length: 15 digits. First four digits must be 2014 or 2149. |
Collect payment data during a voice call and charge a specific amount.
1const VoiceResponse = require('twilio').twiml.VoiceResponse;234const response = new VoiceResponse();5response.say('Calling Twilio Pay');6response.pay({7chargeAmount: '20.45'8});910console.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
1const VoiceResponse = require('twilio').twiml.VoiceResponse;234const response = new VoiceResponse();5response.say('Calling Twilio Pay');6response.pay({7chargeAmount: '20.45',8action: 'https://enter-your-callback-function-url.twil.io/pay'9});1011console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Say>Calling Twilio Pay</Say>4<Pay chargeAmount="20.45"5action="https://enter-your-callback-function-url.twil.io/pay"/>6</Response>
1const VoiceResponse = require('twilio').twiml.VoiceResponse;23const response = new VoiceResponse();4response.pay({tokenType: 'one-time', chargeAmount: '0'});56console.log(response.toString());
1<?xml version="1.0" encoding="UTF-8"?>2<Response>3<Pay tokenType="one-time" chargeAmount="0" />4</Response>