How to capture payment during a voice call (Generic Pay Connector)

Before you continue with this tutorial, you should familiarize yourself with the <Pay> and Generic Pay Connector docs.

To use Twilio's Pay Connectors, you must enable PCI mode in the Twilio Console. This ensures Twilio captures payment details in a PCI-compliant manner and redacts sensitive PCI information from all call logs. Learn more about PCI workflows.

To enable PCI Mode, complete the following steps:

1. Open Voice > Settings > General in Twilio Console or the legacy Console.
2. Select Enable PCI Mode.
3. In the dialog, select I Agree to accept Twilio's Terms of Service.
4. Select Save.

In order for Twilio to send payment information to your payment processor, you must install the Generic Pay Connector on your Twilio Account.

1. Open Pay Connectors in Twilio Console or the legacy Console.
2. Select the Generic Pay Connector tile.
3. Select Install.
4. Give the Generic Pay Connector a UNIQUE NAME of My_Pay_Connector.
5. In the USERNAME and PASSWORD fields, you can put any fake credentials. This is where you would put the credentials used by your payment processor.
6. For now, set the ENDPOINT URL to https://example.com. This is the endpoint where your payment processor will receive HTTPS POST requests from Twilio. You'll create a Twilio Function endpoint to handle these POST requests later in this tutorial.
7. Select Save. Leave this tab open — you'll need it later.

Next, we'll use a TwiML Bin to provide Twilio with the <Pay> TwiML instruction. When Twilio executes the <Pay> verb, a customer will hear prompts to enter their payment information.

1. Open TwiML Bins in Twilio Console or the legacy Console.

2. Select the + button to create a new TwiML Bin.

3. Give the TwiML Bin a FRIENDLY NAME of Generic Pay Connector Tutorial <Pay>.

4. Copy and paste the following TwiML into the TWIML input box:

   Copy code block

   1
   <?xml version="1.0" encoding="UTF-8"?>
   2
   <Response>
   3
    <Pay paymentConnector="My_Pay_Connector" action="" chargeAmount="10.00" />
   4
   </Response>

   Notice how the <Pay> verb has three attributes: paymentConnector, action, and chargeAmount.
   The paymentConnector attribute's value is the Pay Connector you want to use with this <Pay> verb. In this case, it's the Generic Pay Connector you just created called "My_Pay_Connector".
   The action attribute is left blank for now. This attribute will be a URL. Upon the completion of a <Pay> transaction, Twilio will send a webhook to your action URL to get a new set of TwiML instructions. We'll create another TwiML Bin with a new set of TwiML instructions for Twilio to execute after a completed <Pay> transaction and put that new TwiML Bin's URL in this action attribute.
   The chargeAmount attribute is set to 10.00, representing a charge of $10.00. (If you wanted to create a tokenize transaction, you would set this attribute value to 0 or omit the attribute altogether.)

5. Select Save at the bottom of the page.

1. Go to the TwiML Bins page by selecting My TwiML Bins at the top of the page. You can also search for TwiML Bins in the Console's top search bar.

2. Select the + button to create a new TwiML Bin.

3. Give this TwiML Bin a FRIENDLY NAME of "Generic Pay Tutorial Action"

4. In the TWIML input box, paste the follwing TwiML:

   Copy code block

   1
   <?xml version="1.0" encoding="UTF-8"?>
   2
   <Response>
   3
     <Say>Thank you for entering your payment information.</Say>
   4
     {{#PaymentError}}
   5
     <Say>Sorry. There was an error: {{PaymentError}}</Say>
   6
     {{/PaymentError}}
   7
     <Hangup />
   8
   </Response>

   When Twilio executes this TwiML Bin, a caller will hear "Thank you for entering your payment information." and the call will end.

   If Twilio's webhook request to this TwiML Bin contains a PaymentError property (meaning that an error occurred), the caller will also hear "Sorry. There was an error." along with a description of the error before the call ends. (This TwiML Bin uses a conditional content template. Read more about TwiML Templates on the "How to use templates with TwiML Bins" support page.)

5. Select Save at the bottom of the screen. (You'll be asked to confirm due to "invalid" TwiML syntax. It is valid, so ignore this warning.)

6. Find the URL field at the top of the page for this TwiML Bin and copy the URL by selecting Copy to the right of the URL field. You'll set this URL as the action attribute for the other TwiML Bin you created, so that Twilio runs this set of TwiML instructions after the <Pay> verb has completed in your other TwiML Bin.

7. Select My TwiML Bins at the top of the page.

8. Select the Generic Pay Connector Tutorial <Pay> TwiML Bin.

9. Paste the copied URL between the action attribute's quotation marks. Your TwiML Bin should look something like this:

   Copy code block

   1
   <?xml version="1.0" encoding="UTF-8"?>
   2
   <Response>
   3
     <Pay paymentConnector="My_Pay_Connector" action="https://handler.twilio.com/twiml/EHXXXXXXXXXXXXXXXXXXXXXXXXX" chargeAmount="10.00" />
   4
   </Response>

10. Select Save at the bottom of the page.

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

1. Open Buy a number in Twilio Console or the legacy Console.
2. Make sure the Voice checkbox is selected and select Search.
3. You'll see a list of available phone numbers and their capabilities. Find a number that you like and select Buy.
4. In the Review Phone Number dialog, review the information and select Buy (xxx) xxx-xxxx to confirm your purchase.

Now you'll navigate to the configuration page for the phone number and configure it to use your Generic Pay Connector Tutorial <Pay> TwiML Bin when someone calls the number.

1. If you see the Number Purchased modal from the last step, select Configure (xxx) xxx-xxxx. Otherwise, go to Phone Numbers > Active numbers and select the phone number you bought.
2. Give the phone number a FRIENDLY NAME of "Generic Pay Connector Tutorial".
3. Scroll down to the Voice & Fax section.
4. Find the A CALL COMES IN label.
5. Select the Webhook list, then select TwiML Bin.
6. In the Select a TwiML Bin list, select Generic Pay Connector Tutorial <Pay>.
7. Select Save at the bottom of the page.

At this point, you can call your Twilio phone number from another phone. You should hear "Please enter your credit card number."

You can try entering the following test card details:

• Credit card number: 4111 1111 1111 1111
• Expiration date (MM/YY): 12 25 (or any date in the future)
• Zip code: 94105
• CVC security code: 333

You should hear: "Thank you for entering your payment information. Sorry. There was an error: Payment Gateway rejected charge creation. Got malformed response from Payment Provider."

This makes sense, given that our Generic Pay Connector's Endpoint URL was configured to be "https://example.com". That's not a real payment processor.

In the next section, we'll create a very basic endpoint that will be able to handle the POST request that Twilio would send to a payment processor. This is just to illustrate the flow of information between your caller, Twilio, and the payment processor's endpoint.

When <Pay> has completed gathering valid payment information from the caller, the Generic Pay Connector will initiate an HTTPS POST request to the endpoint URL specified in the Pay Connector's configuration.

In an actual, production situation, this is the step where a PCI-compliant payment processor would send the payment information and transaction details (i.e. whether the transaction is a tokenize or charge transaction) with the payment gateway, handle any timeouts or failures from the payment gateway, process any errors, and send back a response to Twilio in Twilio's required format.

For this tutorial, we will create an endpoint that will:

• accept the POST request from Twilio with the transaction information and payment details
• log the request from Twilio so you can understand what Twilio is sending to the payment processor
• return a fake successful response to Twilio

You will use Twilio's Serverless Functionsto write and host this code. Twilio Functions allow you deploy Node.js-based applications without needing to install anything locally on your own machine.

1. Open Functions & assets > Services in Twilio Console, or Functions > Services in the legacy Console.

2. Select Create Service to create a new Functions service.

3. In the Name your Service dialog, give your service the name mock-payment-processor.

4. Select Next on the Name your Service dialog.

5. Select Add + in the top left corner of the page, then select Add Function.

6. In the Functions pane on the top left, find the input that contains /path_1 and change it to /pay, then press Enter.

7. Next to the /pay path name, you should see Protected. Select the downward arrow next to Protected, then select Public.

8. Select all of the provided sample code and delete it.

9. Copy and paste the following code into the code editor of your /pay function:

   Copy code block

   1
   exports.handler = (context, event, callback) => {
   2
     console.log('POST request from Twilio received:');
   3
   
   4
     console.log(event);
   5
   
   6
     console.log('Authorization Headers: ', event.request.headers.authorization);
   7
   
   8
     const sampleResponse = {
   9
         charge_id: "some_id",
   10
         error_code: null,
   11
         error_message: null
   12
     };
   13
   
   14
     return callback(null, sampleResponse);
   15
   };

10. Select Save at the bottom of the code editor pane.

11. Select Deploy All at the bottom of the page. This deploys your Twilio Function to the internet.

12. Turn on the Enable live logs switch so that you'll see live logs when your /pay endpoint receives a request from Twilio.

13. Copy the URL for your new endpoint by selecting Copy URL at the bottom of the code editor pane.

14. Go to your browser tab with the Generic Pay Connector's configuration page. Alternatively, open Pay Connectors in Twilio Console or go to Voice > Manage > Pay Connectors > Generic Pay Connector in the legacy Console.

15. Paste your Twilio Function's URL into the ENDPOINT URL field.

16. Select Save.

Before you call your Twilio phone number, review what should happen:

• You dial your Twilio phone number
• The phone number's configuration points to the "Generic Pay Connector Tutorial <Pay>" TwiML Bin.
• Twilio executes the <Pay> verb, so you hear prompts to enter your payment details.
• You enter your payment details.
• Twilio sends a request to your Twilio Functions endpoint URL (because your <Pay> verb's paymentConnector attribute pointed to your Generic Pay Connector called "My_Pay_Connector", which is configured with your Twilio Functions URL).
• Your Twilio Function (your fake payment processor) returns a response object to Twilio.
• The response object doesn't contain an error, so you hear "Thank you for entering your payment information" and the call ends. This is because once Twilio received a response from your fake payment processor, it sent a POST request to your "Generic Pay Tutorial Action" TwiML Bin. (Remember, the <Pay> verb in the other TwiML Bin had an action attribute that pointed to this TwiML Bin.)

1. Make sure you can see your Twilio Functions Console page for your mock-payment-processor function.

2. Make sure you've turned on the Enable live logs toggle (the toggle now reads Disable live logs).

3. Call your Twilio number.

4. Enter your test payment information:

   • Credit card number: 4111 1111 1111 1111
   • Expiration date (MM/YY): 12 25 (or any date in the future)
   • Zip code: 94105
   • CVC security code: 333

5. In your Twilio Functions log, you should see the logs of your Twilio Function print out something like the following:

   Copy code block

   1
   
   2
   POST request from Twilio received:
   3
   
   4
   { request: '[Object]', transaction_id: '72500aba-328c-445c-a12e-da5700e10b17', 
   5
   cardnumber: '4111111111111111', cvv: '333', expiry_month: '12', 
   6
   expiry_year: '25', description: '[Object]', amount: '10.00', 
   7
   currency_code: 'USD', postal_code: '94150', method: 'charge', 
   8
   parameters: '[Object]' }
   9
   
   10
   Authorization Headers: Basic bXlfY29ubmVjdG9yX3VzZXJuYW1lOnRlc3RpbmcxMjM=
   11
   

   Notice that the card information is not redacted, since it is presumed that the payment processor is PCI-compliant.
   Also, you can see that the request that Twilio sends to the payment processor contains an Authorization header that conforms to HTTP Basic Authentication. It contains the credentials you used in your Generic Pay Connector's configuration in Base64-encoded form. (The above example decoded is: my_connector_username:testing123.)
   Your mock-payment-processor Function also returns an object in the format that Twilio expects:

   Copy code block

   1
   {
   2
     charge_id: "some_id",
   3
     error_code: null,
   4
     error_message: null
   5
   }

6. To see what Twilio sends to your <Pay> verb's action URL, you can go to your Call Logs in your Twilio Console.

   1. In your Twilio Console navigation, go to Monitor > Logs > Calls.

   2. On the Call Logs page, select your most recent Call SID.

   3. In the Request Inspector section, select + Expand All. You should see two POST requests.

   4. Twilio made its first POST request to your Generic Pay Connector Tutorial <Pay> TwiML Bin. (Look at the Response Body to verify this.)

   5. Twilio made a second POST request to the action URL from your <Pay> verb. (Remember that your action URL pointed to your Generic Pay Connector Tutorial Action TwiML Bin.) Inspect the Parameters in this POST Request and see the parameters related to this <Pay> transaction:

      • PaymentCardNumber
      • PaymentConfirmationCode
      • Result
      • SecurityCode
      • PaymentCardType
      • ExpirationDate
      • PaymentCardPostalCode
      • PaymentToken
      • PaymentError

Congratulations! You completed a mock payment with <Pay> and a Generic Pay Connector. You should now understand the flow of information between a caller (your customer), Twilio, and your payment processor.

In order to become production-ready, you'll need to create your own PCI-compliant payment processor or find an existing, PCI-compliant payment processor that can properly respond to Twilio requests, process charge and tokenize transactions with a payment gateway, and handle timeouts and retries.

If you've already chosen a payment processor to work with, you can share the Generic Pay Connector docs with them so they can customize their code to work with Twilio's Generic Pay Connectors.