Payment Resource

Agent-assisted payments allow agents to collect customer payment information in a PCI-compliant manner on Twilio voice calls in the contact center. With agent-assisted payments, the agent stays on the phone and guides the customer through the payment flow, requesting the various required pieces of payment information one item at a time.

The agent can control the payment flow asking for payment information in the order they see best for the customer and even re-request information as needed. When the customer is entering their payment information, the agent will not be able to hear the DTMF (Dual-Tone Multi-Frequency) tones, ensuring PCI DSS (Payment Card Industry Data Security Standard) compliance of the payment information and the security of the customer payment information.

Once the agent has progressed through all the steps to gather the payment information from the customer, they complete the capture via Twilio. Twilio sends the payment information directly to the payment connector for processing, ensuring no card information is ever divulged to the agent.

• Agent requests some information, including payment method, from the customer and begins a Twilio Pay session.
• Agent triggers API calls through their UI to collect specific pieces of payment information from the customer, e.g., credit card number, expiration date, or bank account number.
• The Caller enters the requested payment information using their phone keypad. Agents are not able to hear any DTMF tones.
• Once the customer is done, the agent sees the result of the customer's input, e.g., xxxx xxxx xxxx 4242 or invalid-card-number.
• Agent requests the next piece of required payment information and continues to do so until all the information needed is entered.
  • The agent can re-request a piece of payment information as needed in any order and at any point during the flow.
  • The agent is also able to cancel the payment at any point during the flow.
• Once all the information is collected, the agent completes the Pay session and receives the result of the payment.

With Agent assistance the key is to capture customer information while the Agent is on the call with the customer. This means the agent can interact with the customer guiding them through the experience of entering their card details. A typical agent flow is outlined below:

• The agent collects and enters information like payment method, charge amount or token type, and then starts the Pay session.
• The agent then calls the Update API (through their own UI) for each piece of payment information in succession.
• If customers make a mistake while entering information, the agent simply calls the Update API again to re-capture that particular information.
• Once all the required payment information has been collected, the Agent completes the Pay session by setting the status to complete, which then processes the payment and completes the transaction. The agent can also cancel the Pay session, if required at this stage, by setting the status in the Update API to cancel.
• Resulting information in each of the calls above will be delivered via status callbacks, which can be used to update the agent UI in near real-time.

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Payments.json

Provide an absolute or relative URL for this parameter. Twilio Pay will make a POST request to this URL whenever there is an update to the Parameter being captured. The POST request will have the following parameters:

POST https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Payments/{Sid}.json

Provide an absolute or relative URL for this parameter. Twilio Pay will make a POST request to this URL whenever the Update API is called and whenever there is an update to the Parameter being captured. The POST request will contain all of common StatusCallback parameters as well as these additional parameters:

Indicate whether the current payment session should be cancelled or completed when this API request is made. When the status is cancel, the payment session will be cancelled. You will have to use the Start API to start a new payment session. When the status is complete, Twilio sends the payment information to the selected Pay connector for processing.

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updatePayments() {
11
  const payment = await client
12
    .calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
    .payments("PKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14
    .update({
15
      idempotencyKey: "IdempotencyKey",
16
      status: "complete",
17
      statusCallback: "https://www.example.com",
18
    });
19

20
  console.log(payment.accountSid);
21
}
22

23
updatePayments();

1
{
2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "date_created": "Wed, 18 Dec 2019 20:02:01 +0000",
5
  "date_updated": "Wed, 18 Dec 2019 20:02:01 +0000",
6
  "sid": "PKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments/PKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
8
}

1
// Download the helper library from https://www.twilio.com/docs/node/install
2
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3

4
// Find your Account SID and Auth Token at twilio.com/console
5
// and set the environment variables. See http://twil.io/secure
6
const accountSid = process.env.TWILIO_ACCOUNT_SID;
7
const authToken = process.env.TWILIO_AUTH_TOKEN;
8
const client = twilio(accountSid, authToken);
9

10
async function updatePayments() {
11
  const payment = await client
12
    .calls("CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
13
    .payments("PKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa")
14
    .update({
15
      idempotencyKey: "IdempotencyKey",
16
      status: "cancel",
17
      statusCallback: "https://www.example.com",
18
    });
19

20
  console.log(payment.accountSid);
21
}
22

23
updatePayments();

1
{
2
  "account_sid": "ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
3
  "call_sid": "CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
4
  "date_created": "Wed, 18 Dec 2019 20:02:01 +0000",
5
  "date_updated": "Wed, 18 Dec 2019 20:02:01 +0000",
6
  "sid": "PKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
7
  "uri": "/2010-04-01/Accounts/ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Calls/CAaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa/Payments/PKaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa.json"
8
}

Provide an absolute or relative URL for this parameter. Twilio Pay will make a POST request to this URL whenever the Cancel/Complete API is called. The POST request will contain all of common StatusCallback parameters as well as these additional parameters:

Parameter: DateUpdated

Description:

The date when the Pay session was last updated

Parameter: ConnectorError

Description:

This parameter contains the error code/message received from the underlying payment gateway

Parameter: PayErrorCode

Description:

A numerical error code that gives more details about the error. To learn more about the error, please visit the error page and search for the error code

Parameter: PaymentError

Description:

Payment error for failures. For example, card is declined

Parameter: PaymentConfirmationCode

Description:

If the payment method provided was charged and not tokenized, this is the confirmation code from the Payment Gateway

Parameter: PaymentToken

Description:

The tokenized value of the credit card or ACH payment data. Payment will not be tokenized if a charge amount is provided. Values:

• ACI — Card token
• Base Commerce — BankCard token
• Braintree — token
• CardConnect — token
• Chase — no value
• Stripe — one-time token

Parameter: ProfileId

Description:

The identifier of the customer object to which the payment is associated. Can be used as a token depending on the Connector. Payment will not be tokenized if a charge amount is provided. Values:

• ACI — no value
• Base Commerce — no value
• Braintree — ID of the customer object (cannot be used as a token)
• CardConnect — profile
• Chase — customer reference number
• Stripe — ID of the customer resource

Parameter: Result

Description:

The result of the transaction. See the table below for all the values