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

Payment Resource



Agent-assisted payments

agent-assisted-payments page anchor

Introduction

introduction page anchor

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.

Resource properties
account_sidtype: SID<AC>Not PII

call_sidtype: SID<CA>Not PII

The SID of the Call(link takes you to an external page) the Payments resource is associated with. This will refer to the call sid that is producing the payment card (credit/ACH) information thru DTMF.


sidtype: SID<PK>Not PII

The SID of the Payments resource.


date_createdtype: string<DATE TIME RFC 2822>Not PII

The date and time in GMT that the resource was created specified in RFC 2822(link takes you to an external page) format.


date_updatedtype: string<DATE TIME RFC 2822>Not PII

The date and time in GMT that the resource was last updated specified in RFC 2822(link takes you to an external page) format.


uritype: stringNot PII

The URI of the resource, relative to https://api.twilio.com.


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

Parameters

create-parameters page anchor
URI parameters
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) that will create the resource.


CallSidtype: SID<CA>Not PII
Path Parameter

The SID of the call that will create the resource. Call leg associated with this sid is expected to provide payment information thru DTMF.


Request body parameters
IdempotencyKeytype: stringNot PII
Required

A unique token that will be used to ensure that multiple API calls with the same information do not result in multiple transactions. This should be a unique string value per API call and can be a randomly generated.


StatusCallbacktype: string<URI>Not PII
Required

Provide an absolute or relative URL to receive status updates regarding your Pay session. Read more about the expected StatusCallback values(link takes you to an external page)


BankAccountTypetype: enum<STRING>Not PII

Type of bank account if payment source is ACH. One of consumer-checking, consumer-savings, or commercial-checking. The default value is consumer-checking.

Possible values:
consumer-checkingconsumer-savingscommercial-checking

ChargeAmounttype: numberNot PII

A positive decimal value less than 1,000,000 to charge against the credit card or bank account. Default currency can be overwritten with currency field. Leave blank or set to 0 to tokenize.


Currencytype: stringNot PII

The currency of the charge_amount, formatted as ISO 4127(link takes you to an external page) format. The default value is USD and all values allowed from the Pay Connector are accepted.


Descriptiontype: stringNot PII

The description can be used to provide more details regarding the transaction. This information is submitted along with the payment details to the Payment Connector which are then posted on the transactions.


Inputtype: stringNot PII

A list of inputs that should be accepted. Currently only dtmf is supported. All digits captured during a pay session are redacted from the logs.


MinPostalCodeLengthtype: integerNot PII

A positive integer that is used to validate the length of the PostalCode inputted by the user. User must enter this many digits.


Parametertype: objectNot PII

A single-level JSON object used to pass custom parameters to payment processors. (Required for ACH payments). The information that has to be included here depends on the <Pay> Connector. Read more(link takes you to an external page).


PaymentConnectortype: stringNot PII

This is the unique name corresponding to the Pay Connector installed in the Twilio Add-ons. Learn more about <Pay> Connectors(link takes you to an external page). The default value is Default.


PaymentMethodtype: enum<STRING>Not PII

Type of payment being captured. One of credit-card or ach-debit. The default value is credit-card.

Possible values:
credit-cardach-debit

PostalCodetype: booleanNot PII

Indicates whether the credit card postal code (zip code) is a required piece of payment information that must be provided by the caller. The default is true.


SecurityCodetype: booleanNot PII

Indicates whether the credit card security code is a required piece of payment information that must be provided by the caller. The default is true.


Timeouttype: integerNot PII

The number of seconds that <Pay> should wait for the caller to press a digit between each subsequent digit, after the first one, before moving on to validate the digits captured. The default is 5, maximum is 600.


TokenTypetype: enum<STRING>Not PII

Indicates whether the payment method should be tokenized as a one-time or reusable token. The default value is reusable. Do not enter a charge amount when tokenizing. If a charge amount is entered, the payment method will be charged and not tokenized.

Possible values:
one-timereusable

ValidCardTypestype: stringNot PII

Credit card types separated by space that Pay should accept. The default value is visa mastercard amex

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_14
// Download the helper library from https://www.twilio.com/docs/node/install
_14
// Find your Account SID and Auth Token at twilio.com/console
_14
// and set the environment variables. See http://twil.io/secure
_14
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_14
const authToken = process.env.TWILIO_AUTH_TOKEN;
_14
const client = require('twilio')(accountSid, authToken);
_14
_14
client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_14
.payments
_14
.create({
_14
idempotencyKey: 'idempotency_key',
_14
statusCallback: 'https://example.com'
_14
})
_14
.then(payment => console.log(payment.sid));

Output

_10
{
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"date_created": "Wed, 18 Dec 2019 20:02:01 +0000",
_10
"date_updated": "Wed, 18 Dec 2019 20:02:01 +0000",
_10
"sid": "PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Payments/PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_10
}

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:

ParameterDescription
AccountSidThe unique identifier of the Account responsible for this pay session
CallSidThe unique identifier for the call associated with the pay session. CallSid will always refer to the parent leg of a two-leg call
SidThe unique identifier of the current Pay session
DateCreatedThe date when the Pay session was started
BankAccountTypeIf the ach-debit PaymentMethod is used, the Bank Account Type provided by the caller and entered by the agent
ChargeAmountIf not tokenizing — i.e., the charge amount is specified and greater than zero — the amount to charge the payment method
PaymentConnectorThe unique name of Payment Connector corresponding to the Pay Connector installed in the Twilio Add-ons
PaymentMethodAch-debit or credit-card
TokenTypeOne-time or reusable if charge amount not specified
(information)

Info

All StatusCallback requests will contain these fields. Additional StatusCallback values can be found during the Update and Complete/Cancel APIs.


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

URI parameters
AccountSidtype: SID<AC>Not PII
Path Parameter

The SID of the Account(link takes you to an external page) that will update the resource.


CallSidtype: SID<CA>Not PII
Path Parameter

The SID of the call that will update the resource. This should be the same call sid that was used to create payments resource.


Sidtype: SID<PK>Not PII
Path Parameter

The SID of Payments session that needs to be updated.


Request body parameters
IdempotencyKeytype: stringNot PII
Required

A unique token that will be used to ensure that multiple API calls with the same information do not result in multiple transactions. This should be a unique string value per API call and can be a randomly generated.


StatusCallbacktype: string<URI>Not PII
Required

Provide an absolute or relative URL to receive status updates regarding your Pay session. Read more about the Update(link takes you to an external page) and Complete/Cancel(link takes you to an external page) POST requests.


Capturetype: enum<STRING>Not PII

The piece of payment information that you wish the caller to enter. Must be one of payment-card-number, expiration-date, security-code, postal-code, bank-routing-number, or bank-account-number.

Possible values:
payment-card-numberexpiration-datesecurity-codepostal-codebank-routing-numberbank-account-number

Statustype: enum<STRING>Not PII

Indicates whether the current payment session should be cancelled or completed. When cancel the payment session is cancelled. When complete, Twilio sends the payment information to the selected Pay Connector for processing.

Possible values:
completecancel

Make this API request for each piece of payment information that you wish

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.payments('PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.update({
_15
capture: 'payment-card-number',
_15
idempotencyKey: 'request-4',
_15
statusCallback: 'https://example.com'
_15
})
_15
.then(payment => console.log(payment.callSid));

Output

_10
{
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"date_created": "Wed, 18 Dec 2019 20:02:01 +0000",
_10
"date_updated": "Wed, 18 Dec 2019 20:02:01 +0000",
_10
"sid": "PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Payments/PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_10
}

StatusCallback (Update)

statuscallback-update page anchor

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:

ParameterDescription
DateUpdatedThe date when the Pay session was last updated
BankAccountNumberIf the PaymentMethod is arch-debit the Bank Account Number entered by the caller. Twilio will only return the last two digits. For example, if the Bank Account Number is 508862392, then Pay will return BankAccountNumber=*******92
BankRoutingNumberIf the PaymentMethod is arch-debit the Bank Routing Number provided by the caller. Twilio will return the full routing number entered. For example, if caller enters 121181976 as their Bank Routing Number provided, then Pay will return BankRoutingNumber=121181976
CaptureThe piece of payment information that Pay was expecting
ChargeAmountIf not tokenizing — i.e., the charge amount was specified and greater than zero — the amount to charge the payment method
ErrorTypeThe full list of error types is visible here
ExpirationDateIf the PaymentMethod is credit-card, the expiration date that is input by the caller. For example, ExpirationDate=0522. The expiration date is not PCI data, so it can be clearly visible
PartialResulttrue if DTMF is still being captured and false once all the digits of the piece of payment information being captured have been entered
PaymentCardNumberIf the PaymentMethod is credit-card, the card number input by the caller with only the last 4 digits visible. For example, PaymentCardNumber=xxxx-xxxxxx-x4001
PaymentCardPostalCodeIf the PaymentMethod is credit-card, the postal code inout by the caller or by the agent. For example, PaymentCardPostalCode=94109. Postal Code is not PCI data, so it can be clearly visible.
PaymentCardTypeIf the PaymentMethod is credit-card, the type of card input by the caller. For example, PaymentCardType=amex. The value provided here will be one of the values provided with the cardTypes parameter in the Start API
RequiredThe pieces of payment information that remain to be collected. For example, if postal code and security code are false and credit card number has already been input, then Required=ExpirationDate
SecurityCodeIf the PaymentMethod is credit-card, the security code input by the caller with all digits redacted, for example, SecurityCode=xxx

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.

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.payments('PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.update({
_15
status: 'complete',
_15
idempotencyKey: 'idempotency_key',
_15
statusCallback: 'https://example.com'
_15
})
_15
.then(payment => console.log(payment.callSid));

Output

_10
{
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"date_created": "Wed, 18 Dec 2019 20:02:01 +0000",
_10
"date_updated": "Wed, 18 Dec 2019 20:02:01 +0000",
_10
"sid": "PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Payments/PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_10
}

Node.js
Python
C#
Java
Go
PHP
Ruby
twilio-cli
curl

_15
// Download the helper library from https://www.twilio.com/docs/node/install
_15
// Find your Account SID and Auth Token at twilio.com/console
_15
// and set the environment variables. See http://twil.io/secure
_15
const accountSid = process.env.TWILIO_ACCOUNT_SID;
_15
const authToken = process.env.TWILIO_AUTH_TOKEN;
_15
const client = require('twilio')(accountSid, authToken);
_15
_15
client.calls('CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.payments('PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX')
_15
.update({
_15
status: 'cancel',
_15
idempotencyKey: 'idempotency_key',
_15
statusCallback: 'https://example.com'
_15
})
_15
.then(payment => console.log(payment.callSid));

Output

_10
{
_10
"account_sid": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"call_sid": "CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"date_created": "Wed, 18 Dec 2019 20:02:01 +0000",
_10
"date_updated": "Wed, 18 Dec 2019 20:02:01 +0000",
_10
"sid": "PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
_10
"uri": "/2010-04-01/Accounts/ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Calls/CAXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX/Payments/PKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.json"
_10
}

StatusCallback (Cancel/Complete)

statuscallback-cancelcomplete page anchor

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

ResultDescription
successTwilio successfully captured the payment data and either tokenized or processed the payment
payment-connector-errorTwilio Pay experienced an error communicating with Payment Gateway
caller-interrupted-with-starCaller pressed the * (star) key to interrupt the Pay session
caller-hung-upThe caller hung up the call
validation-errorAn invalid parameter value, e.g., chargeAmount="-0.5"

Rate this page: