Generic Pay Connector

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

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 page.

2. Make sure the "Voice" checkbox is checked and click the Search button.

   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>

   
   

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

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

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.

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.

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

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

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

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).

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.

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.

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.

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

Once you've completed your testing and are ready to move to LIVE mode with your Generic Pay Connector, contact Twilio Support 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.

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

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.

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

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.

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.

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:

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.)

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>.