Skip to contentSkip to navigationSkip to topbar
Rate this page:
On this page

Generic Pay Connector


Twilio's Generic Pay Connector allows you to accept payments securely over the phone via self-service (with the <Pay> verb) or agent assistance without having to become PCI Compliant(link takes you to an external page). Unlike Twilio's other branded Pay Connectors, the Generic Pay Connector allows you to connect to the payment processor of your choice.

The Generic Pay Connector acts as a bridge between you and the payment processor. Your payment processor is responsible for processing the transaction and reporting the result back to Twilio.

You should use Twilio's Generic Pay Connector if your payment processor of choice is not included in Twilio's list of branded Pay Connectors (Stripe, CardConnect, Base Commerce, Chase Paymentech, Braintree or Adyen).

This page will show you:

  • how the Generic Pay Connector works with Twilio and your payment processor to handle payment transactions
  • how to set up a Generic Pay Connector to capture payments
  • the shape of the request and response objects expected by Twilio when communicating with your payment processor

Generic Pay Connector Architecture

generic-pay-connector-architecture page anchor
2022-03-28 at 3.04.53 PM.

If a Generic Pay Connector is installed and configured with a payment processor, the general information flow when collecting payment information is as follows:

  1. A call is established with your Twilio phone number and your customer.
  2. Twilio executes a <Pay> verb. The customer will hear prompts to enter their credit card number, expiration date, zip code, and CVV. (Alternatively, a call center agent could collect payment details using Agent Assist .)
  3. Twilio passes this payment information to your Generic Pay Connector.
  4. The Generic Pay Connector passes the payment information to its specified payment processor using an HTTPS POST request.
  5. The payment processor facilitates the actual payment transaction and passes the result of the transaction back to the Generic Pay Connector.
  6. Twilio sends this information as an HTTP request to the action URL specified in the <Pay> verb (or to the statusCallback URL if using the Payments API)

The Generic Pay Connector only passes information to your payment processor. The actual processing of the transaction by the payment processor is outside the scope of the Generic Pay Connector.

Note on payment processors versus payment gateways

A payment processor executes the transaction by transmitting data between you, the merchant; the issuing bank (i.e., the bank that issued your customer's credit card); and the acquiring bank (i.e., your bank).

A payment gateway is a tool that securely transmits the online payment data to the processor to continue the lifecycle of the transaction. A payment gateway also communicates the approval or decline back to the merchant or the customer.


Install and Configure a Generic Pay Connector

install-and-configure-a-generic-pay-connector page anchor

This section describes the prerequisites for using a Generic Pay Connector, and how to install and configure a Generic Pay Connector.

Prerequisites

prerequisites page anchor

Purchase a Voice-enabled Twilio phone number

If you don't already own a Twilio Voice-enabled phone number, complete the following steps:

  1. In the Twilio Console, navigate to the Buy a Number(link takes you to an external page) page.
  2. Make sure the "Voice" checkbox is checked and click the Search button.

    Search for a Number - Click on the 'Search' button.
  3. You'll see a list of available phone numbers and their capabilities. Find a number that you like and click the Buy button.

    Buy a phone number - click on the 'Buy' button on the right side of the screen.
  4. In the"Review Phone Number" pop-up, review the information and click on Buy (xxx) xxx-xxxx to confirm your purchase.

Enable PCI Mode

In order to use any of Twilio's Pay Connectors, you must enable PCI mode on your Twilio account. This ensures that Twilio will capture the payment details from your customers in a PCI-compliant manner and redact any sensitive PCI information from any call logs.

To enable PCI Mode, complete the following steps:

  1. Navigate to the Twilio Voice Settings(link takes you to an external page) in the Twilio Console. (In the left navigation pane, click on Voice > Settings > General .)
  2. Click on the Enable PCI Mode button.

    Enable PCI Mode.
  3. Click on I Agree on the pop up to accept Twilio's Terms of Service.
  4. Click on the Save button.

Install the Generic Pay Connector

install-the-generic-pay-connector page anchor

In order for Twilio to create charges and tokens on your behalf, you must install the Generic Pay Connector on your Twilio Account.

  1. In the Twilio Console, navigate to the Pay Connectors(link takes you to an external page) page. (In the left hand navigation pane, click on Voice > Manage > Pay Connectors .)
  2. Click on the Generic Pay Connector tile.\

    Generic Pay Connector Console tile.
  3. Click on Install .

Configure the Generic Pay Connector

configure-the-generic-pay-connector page anchor
  1. Give the Generic Pay Connector a UNIQUE NAME . (You can give one Pay Connector per Twilio account the name "Default". When using <Pay> , if no paymentConnector attribute is specified, the default Pay Connector is used.)
  2. Add the credentials you use for your payment processor under the USERNAME and PASSWORD field.
  3. Enter the ENDPOINT URL for your payment processor's infrastructure. This is where Twilio will send your customers' payment information.
  4. Click Save .
(warning)

Warning

By default, your Generic Pay Connector will be in TEST mode and you will not be able to update it to LIVE through the Console without contacting Twilio Support. See the section Go live with your Generic Pay Connector below for more information.

Configure Generic Pay Connector: Fill out unique name, username, password, and endpoint URL for your payment processor.

Once you've installed and configured the Generic Pay Connector, you're ready to test your connection to your payment gateway (the URL you just configured) in the TEST mode with test card information. See the section Valid test credit card and bank account numbers below for more information.

You can use either the <Pay> TwiML verb or Agent Assist (using the Payments API) to test the payment flow. Using <Pay> will prompt customers using an automated voice, while Agent Assist allows a call center agent to prompt the customer to enter their payment details.

The following section contains code samples for how to collect payment information with the <Pay> verb while in TEST mode.


Supported transaction types

supported-transaction-types page anchor

Twilio supports two transaction types: charge and tokenize.

A charge transaction means you want to immediately capture funds from the customer's supplied payment method (i.e. credit card, ACH-debit) in return for the goods or services you offer.

If you want to process a charge transaction using a Generic Pay Connector, you will need to include a chargeAmount attribute in your <Pay> verb or when starting a Pay session with the Payments API, and the value of the chargeAmount must be greater than 0.

Create a charge transaction with <Pay>

create-a-charge-transaction-with-pay page anchor

Click on your Helper Library language of choice or click on SHOW SAMPLE RESPONSE to see the raw TwiML.

Node.js
Python
C#
Java
PHP
Ruby

_10
const VoiceResponse = require('twilio').twiml.VoiceResponse;
_10
_10
const response = new VoiceResponse();
_10
response.pay({
_10
chargeAmount: '10.00',
_10
paymentConnector: 'My_Pay_Connector',
_10
action: 'https://your-callback-function-url.com/pay'
_10
});
_10
_10
console.log(response.toString());

Output

_10
<?xml version="1.0" encoding="UTF-8"?>
_10
<Response>
_10
<Pay chargeAmount="10.00" paymentConnector="My_Pay_Connector" action="https://your-callback-function-url.com/pay" />
_10
</Response>

Charge transaction request to payment processor

charge-transaction-request-to-payment-processor page anchor

Once you've collected your customer's payment details, your Generic Pay Connector will send an HTTPS POST request to the configured URL of your payment processor. Below is an example of the body of the POST request that will be sent for a charge transaction. Note that there is a "method" property with a value of "charge", which indicates the type of transaction.

Below is an example request for a credit-card charge transaction


_16
{
_16
"method" : "charge",
_16
"transaction_id" : "transaction_id",
_16
"cardnumber" : "4111111111111111",
_16
"cvv":"123",
_16
"amount":"10.0",
_16
"currency_code":"USD",
_16
"expiry_month":"08",
_16
"expiry_year":"2022",
_16
"description":"pizza",
_16
"postal_code":"94111",
_16
"parameters" : {
_16
"customer_defined_key_1" : "customer_defined_value_1",
_16
"customer_defined_key_2" : "customer_defined_value_2"
_16
}
_16
}

Below is an example request for an ach-debit charge transaction


_13
{
_13
"method" : "charge",
_13
"transaction_id" : "transaction_id",
_13
"bankaccountnumber" : "4111111111111111",
_13
"routingnumber" : "12345678",
_13
"amount":"10.0",
_13
"currency_code":"USD",
_13
"description":"pizza",
_13
"parameters" : {
_13
"customer_defined_key_1" : "customer_defined_value_1",
_13
"customer_defined_key_2" : "customer_defined_value_2"
_13
}
_13
}

Charge transaction response from payment processor to Twilio

charge-transaction-response-from-payment-processor-to-twilio page anchor

Payment processors will take the request object from above, handle the charge transaction, and return an object to Twilio that contains an ID number for the charge transaction, any applicable error code/message, and any custom parameters if necessary.

Below is an example response object that Twilio would expect from a payment processor after it handles a charge transaction. Note that there is a "charge_id" property with a value of some identification number associated with the charge transaction.


_10
{
_10
"charge_id":"some_id",
_10
"error_code":null,
_10
"error_message":null
_10
}

Twilio's Request to your action URL or statusCallback URL (charge transaction)

twilios-request-to-your-action-url-or-statuscallback-url-charge-transaction page anchor

Twilio will receive and format the response from the payment processor.

If you used the <Pay> verb, Twilio will send this information in the body of a POST request to the action URL

If you used the Payment API, Twilio will send this information in the body of a POST request to the statusCallback URL you specified when you created the Payment session.

A tokenize transaction means you want to obtain a token based on the user's supplied payment information (e.g. credit card or ACH-debit 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 payment information again. Note that tokens are provided by your payment gateway or processor.

To make a tokenize transaction, you must set the chargeAmount to "0" or omit the chargeAmount attribute from your <Pay> verb or when you start a new Pay session using the Payment API.

Create a tokenize transaction with <Pay>

create-a-tokenize-transaction-with-pay page anchor

Click on your Helper Library language of choice or click on SHOW SAMPLE RESPONSE to see the raw TwiML.

Node.js
Python
C#
Java
PHP
Ruby

_10
const VoiceResponse = require('twilio').twiml.VoiceResponse;
_10
_10
const response = new VoiceResponse();
_10
response.pay({
_10
chargeAmount: '0',
_10
paymentConnector: 'My_Pay_Connector',
_10
action: 'https://your-callback-function-url.com/pay'
_10
});
_10
_10
console.log(response.toString());

Output

_10
<?xml version="1.0" encoding="UTF-8"?>
_10
<Response>
_10
<Pay chargeAmount="0" paymentConnector="My_Pay_Connector" action="https://your-callback-function-url.com/pay" />
_10
</Response>

Tokenize transaction request to payment processor

tokenize-transaction-request-to-payment-processor page anchor

Once you've collected your customer's payment details, your Generic Pay Connector will send a POST request to the configured URL of your payment processor. Below is an example of the body of the POST request that will be sent. Note that there is a "method" property with a value of "tokenize", which indicates the type of transaction.

Below is an example request for a credit-card tokenize transaction


_14
{
_14
"method" : "tokenize",
_14
"transaction_id" : "transaction_id",
_14
"cardnumber" : "4111111111111111",
_14
"cvv":"123",
_14
"expiry_month":"08",
_14
"expiry_year":"2022",
_14
"description":"pizza",
_14
"postal_code":"94111",
_14
"parameters" : {
_14
"customer_defined_key_1" : "customer_defined_value_1",
_14
"customer_defined_key_2" : "customer_defined_value_2"
_14
}
_14
}

Below is an example request for an ach-debit tokenize transaction


_11
{
_11
"method" : "tokenize",
_11
"transaction_id" : "transaction_id",
_11
"bankaccountnumber" : "4111111111111111",
_11
"routingnumber" : "12345678",
_11
"description":"pizza",
_11
"parameters" : {
_11
"customer_defined_key_1" : "customer_defined_value_1",
_11
"customer_defined_key_2" : "customer_defined_value_2"
_11
}
_11
}

Tokenize transaction response from payment processor to Twilio

tokenize-transaction-response-from-payment-processor-to-twilio page anchor

Payment processors will take the request object from above, handle the tokenize transaction, and return an object to Twilio that contains an ID number for the tokenize transaction, any applicable error code/message, and any custom parameters if necessary.

Below is an example response object that Twilio would expect from a payment processor after it handles a tokenize transaction. Note that there is a "token_id" property with a value of some identification number associated with the tokenize transaction (or the token itself, depending on the payment processor).


_10
{
_10
"token_id":"any_token",
_10
"error_code":null,
_10
"error_message":null
_10
}

Twilio's response to your application (tokenize transaction)

twilios-response-to-your-application-tokenize-transaction page anchor

Twilio will receive and format the response from the payment processor.

If you used the <Pay> verb, Twilio will send this information in the body of a POST request to the action URL

If you used the Payment API, Twilio will send this information in the body of a POST request to the statusCallback URL you specified when you created the Payment session.


Valid test credit card and bank account numbers

valid-test-credit-card-and-bank-account-numbers page anchor

While in TEST mode, Twilio allows you to perform testing against your configured payment gateway URL with the test credit card numbers and bank account numbers listed below. Any other credit card number or bank account number will be blocked. If using <Pay>, your action URL will receive an error response.

Valid test credit card numbers

valid-test-credit-card-numbers page anchor
Card TypeNumber
Visa4111111111111111
MasterCard5555555555554444
American Express378282246310005
Discover6011111111111117
Diner's Club3065930009020004
JCB3566002020360505
UnionPay6200000000000005
Maestro6771798021000008

Please note that for credit card transactions, any valid expiration date, CVV, and postal code combination will work in TEST mode with the above credit card numbers.

Valid test bank account numbers

valid-test-bank-account-numbers page anchor
Card TypeNumber
8-Digit12345678
9-Digit123456789

Please note that any valid bank routing number will work in TEST mode with the above bank account numbers.

Go live with your Generic Pay Connector

go-live-with-your-generic-pay-connector page anchor

Once you've completed your testing and are ready to move to LIVE mode with your Generic Pay Connector, contact Twilio Support(link takes you to an external page) for approval.

In order to approve your connector for LIVE mode, you must submit the following:

  • the latest, non-expired Attestation of Compliance (AOC) from your payment gateway
  • the URL of your payment gateway
  • confirmation that you have reviewed the PCI-compliance of your downstream payment gateway

Twilio will validate this payment gateway URL against your Connector's configured URL that you set in TEST mode to ensure it points to your payment gateway, and then approve your Generic Pay Connector. Once approved, you can move your Connector to LIVE mode in the Console and your payment gateway URL will become immutable.

(warning)

Warning

While in TEST mode, you can change the payment gateway URL as many times as you want.

Once you change the Connector to LIVE mode, the Connector's payment gateway URL is no longer editable.

If you need to change the payment gateway URL after switching to LIVE mode, you must open a Support ticket with the following information:

  • the latest, non-expired Attestation of Compliance (AOC) from your payment gateway
  • the new payment gateway URL you wish to use
  • confirmation that you have reviewed the PCI-compliance of your downstream payment gateway

Twilio allows you to send custom parameters in the request to the payment processor, as well as receive custom parameters from the payment processor.

Send custom parameters to payment processor

send-custom-parameters-to-payment-processor page anchor

If you use the <Pay> verb, you can send custom parameters to your payment processor using the <Parameter> noun. This functionality could be used to send additional contextual information about the transaction. For example, you could inform the payment processor to waive fees, charge fees, process a refund, etc. Your specific use case and your chosen payment processor will determine what these custom parameters should be.

The <Parameter> noun is nested within the <Pay> verb's open and closing tags, and takes name and value attributes for the name and value of your custom parameter. (See "Pay charge transaction with Parameter noun" code sample below.)

The example below shows a charge transaction using the <Parameter> noun to pass custom parameters to the payment processor.

You can also pass custom parameters for tokenize transactions in the same manner.

There is no limit to the number of custom parameters you can nest within a <Pay> verb.

Pass custom parameters with <Pay> and <Parameter>

pass-custom-parameters-with-pay-and-parameter page anchor

Click on your Helper Library language of choice or click on SHOW SAMPLE RESPONSE to see the raw TwiML.

Node.js
Python
C#
Java
PHP
Ruby

_14
const VoiceResponse = require('twilio').twiml.VoiceResponse;
_14
_14
const response = new VoiceResponse();
_14
const pay = response.pay({
_14
chargeAmount: '10.00',
_14
paymentConnector: 'My_Generic_Pay_Connector',
_14
action: 'https://your-callback-function-url.com/pay'
_14
});
_14
pay.parameter({
_14
name: 'custom_parameter_1',
_14
value: 'custom_value_1'
_14
});
_14
_14
console.log(response.toString());

Output

_10
<?xml version="1.0" encoding="UTF-8"?>
_10
<Response>
_10
<Pay chargeAmount="10.00" paymentConnector="My_Generic_Pay_Connector" action="https://your-callback-function-url.com/pay">
_10
<Parameter name="custom_parameter_1" value="custom_value_1" />
_10
</Pay>
_10
</Response>

The body of the POST request that your Generic Pay Connector sends to the payment processor will include the custom parameters in a "parameters" property as shown below.


_15
{
_15
"method" : "charge",
_15
"transaction_id" : "transaction_id",
_15
"cardnumber" : "4111111111111111",
_15
"cvv":"123",
_15
"amount":"10.0",
_15
"currency_code":"USD",
_15
"expiry_month":"08",
_15
"expiry_year":"2022",
_15
"description":"pizza",
_15
"postal_code":"94111",
_15
"parameters" : {
_15
"custom_parameter_1" : "custom_value_1"
_15
}
_15
}

Receive custom parameters from payment processor

receive-custom-parameters-from-payment-processor page anchor

Twilio also can handle receiving custom parameters from your payment processor.

After your payment processor handles your transaction, the response body it sends back can contain a parameters property as shown in the example below.

(warning)

Warning

Receiving custom parameters to the payment processor is not possible with the Payments API/Agent Assist at this time.


_10
{
_10
"charge_id":"any_id",
_10
"error_code":null,
_10
"error_message":null,
_10
"parameters" : {
_10
"key1_from_payment_processor" : "value1_from_payment_processor",
_10
"key2_from_payment_processor" : "value2_from_payment_processor"
_10
}
_10
}

These custom parameters will then be added as properties (with their names prepended with PayConnector_) on the POST request body to your action URL. (Read more about the shape of the POST request body on the <Pay> doc's action section.)

For example, given the sample response from the payment processor above, the body of Twilio POST request to your action URL could include the following properties:


_10
PayConnector_key1_from_payment_processor: "value1_from_payment_processor",
_10
PayConnector_key2_from_payment_processor: "value2_from_payment_processor"


Error Handling and Retry Mechanism

error-handling-and-retry-mechanism page anchor

If the payment processor fails to respond to Twilio's request within 10 seconds, Twilio will retry the request up to 5 times, passing the same transaction_id in the retried request.

It is up to the payment processor to handle the retried request properly. If the transaction is still in progress and succeeds after more than 10 seconds from the initial request, Twilio will expect the successful response to be returned to the retried request.

For example, in the case where the payment processor takes 11 seconds to process a successful transaction, the charge_id should be returned to the retry request made by Twilio.

In other words, if a duplicate transaction is attempted, either an error should be returned to Twilio stating it was a duplicate transaction, or the original charge_id / token_id (from the payment processor's first attempted response to Twilio) should be returned.

The transaction_id behaves as an idempotency token to avoid duplicate charges done by the payment processor in the case where a response is dropped in transit to Twilio.

Any non-NULL error code returned from a payment processor or customer's infrastructure will be returned to the customer in the connectorError field sent as part of the payload to the action URL specified in the <Pay> verb. (Read more about the shape of the POST request body on the <Pay> doc's action section.)

Expected Error Response Structure from Payment Processor

expected-error-response-structure-from-payment-processor page anchor

In case of an error, Twilio will expect to receive the charge_id field in the response for a charge error and the token_id field in the response for a tokenize error from the payment processor. The parameters field is optional.


Try out this Generic Pay Connector tutorial, which walks through the setup of a Generic Pay Connector and a TwiML Bin using <Pay>.


Rate this page: