Menu

Expand
Rate this page:

Payment Resource

Agent Assisted Payments

Introduction

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 required various 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 inputting their payment information, the agent will not be able to hear the DTMF (dual tone multi frequency), ensuring the security of the payment information and the customer.

Once the agent has all the information they need, they complete the payment and Twilio sends to the connector for processing.

Workflow

  • 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, bank account number)
  • Caller enters the requested payment information via DTMF. Agent is not able to hear any DTMF that the customer enters.
  • 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 is able to 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 e.g., success

API design

Agent collects and enters information like payment method, charge amount, or token type and then starts the pay session. Then the agent calls the Update API (through their own UI) for each piece of payment information. Once all the required payment information is collected through the Update API, the Agent then 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 by setting the status to cancel.

Resulting information will be delivered via status callbacks.

Payments properties

Resource Properties in REST API format
account_sid
sid<AC> Not PII

The SID of the Account that created the Payments resource.

call_sid
sid<CA> Not PII

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

sid
sid<PK> Not PII

The SID of the Payments resource.

date_created
date_time<rfc2822> Not PII

The date and time in GMT that the resource was created specified in RFC 2822 format.

date_updated
date_time<rfc2822> Not PII

The date and time in GMT that the resource was last updated specified in RFC 2822 format.

uri
uri Not PII

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

Starting a Pay session

post
https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Payments.json
Parameters
Parameters in REST API format
account_sid
Path
post sid<AC> Not PII

The SID of the Account that will create the resource.

call_sid
Path
post sid<CA> Not PII

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

idempotency_key
Required
post string Not PII

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.

status_callback
Required
post url Not PII

Provide an absolute or relative URL to receive status updates regarding your Pay session. Read more about the expected StatusCallback values

bank_account_type
Optional
post ienum:bank_account_type 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.

charge_amount
Optional
post decimal Not 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.

currency
Optional
post string Not PII

The currency of the charge_amount, formatted as ISO 4127 format. The default value is USD and all values allowed from the Connector are accepted.

description
Optional
post string Not 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.

input
Optional
post string Not 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.

min_postal_code_length
Optional
post integer Not PII

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

parameter
Optional
post object Not PII

A single level JSON string that is required when accepting certain information specific only to ACH payments. The information that has to be included here depends on the Connector. Read more.

payment_connector
Optional
post string Not PII

This is the unique name corresponding to the Payment Gateway Connector installed in the Twilio Add-ons. Learn more about Connectors. The default value is Default.

payment_method
Optional
post ienum:payment_method Not PII

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

postal_code
Optional
post boolean Not 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.

security_code
Optional
post boolean Not 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.

timeout
Optional
post integer Not PII

The number of seconds that 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.

token_type
Optional
post ienum:token_type 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.

valid_card_types
Optional
post string Not PII

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

Example 1
        
        
        
        

        StatusCallback

        Provide an absolute or relative URL for this parameter. Twilio Pay will make a POST request to this URL with the whenever this API is called. The POST request will have the following parameters.

        Parameter

        Description

        AccountSid

        The unique identifier of the Account responsible for this pay session

        CallSid

        The unique identifier for the call associated with the pay session. CallSid will always refer to the parent leg of a two-leg call

        Sid

        The unique identifier of the current Pay session

        DateCreated

        The date when the Pay session was started

        BankAccountType

        If ach-debit PaymentMethod is used, the Bank Account Type provided by the caller and entered by the agent

        ChargeAmount

        If not tokenizing (i.e. charge amount specified and greater than 0), the amount to charge the payment method

        PaymentConnector

        The unique name of Payment Connector corresponding to the Payment Gateway Connector installed in the Twilio Add-ons

        PaymentMethod

        Ach-debit or credit-card

        TokenType

        One-time or reusable if charge amount not specified

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

        Update a Pay session

        post
        https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Payments/{Sid}.json
        Parameters
        Parameters in REST API format
        account_sid
        Path
        post sid<AC> Not PII

        The SID of the Account that will update the resource.

        call_sid
        Path
        post sid<CA> Not PII

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

        sid
        Path
        post sid<PK> Not PII

        The SID of Payments session that needs to be updated.

        idempotency_key
        Required
        post string Not PII

        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.

        status_callback
        Required
        post url Not PII

        Provide an absolute or relative URL to receive status updates regarding your Pay session. Read more about the Update and Complete/Cancel POST requests.

        capture
        Optional
        post ienum:capture 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.

        status
        Optional
        post ienum:status 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 connector for processing.

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

              Update a Pay session

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

              StatusCallback (Update)

              Provide an absolute or relative URL for this parameter. Twilio Pay will make a POST request to this URL with the 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:

              Parameter

              Description

              DateUpdated

              The date when the Pay session was last updated

              BankAccountNumber

              If the ach-debit PaymentMethod is used, the Bank Account Number entered by the caller. Twilio will only return the last 2 digits. For example, if the Bank Account Number is 508862392, then Pay will return BankAccountNumber=*******92

              BankRoutingNumber

              If the ach-debit paymentMethod used, 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

              Capture

              The piece of payment information that Pay was expecting

              ChargeAmount

              If not tokenizing (i.e. charge amount specified and greater than 0), the amount to charge the payment method

              ErrorType

              The full list of error types is visible here.

              ExpirationDate

              If the PaymentMethod is credit card, the expiration date that is input by the caller. For example, ExpirationDate=0522


              Note: Expiration date is not PCI data, so it can be clearly visible.

              PartialResult

              "true" if DTMF is still being captured and "false" once all the digits of the piece of payment information being captured have been entered.

              PaymentCardNumber

              If credit-card paymentMethod is used, the card number input by the caller with only the last 4 digits visible. For example, PaymentCardNumber=xxxx-xxxxxx-x4001

              PaymentCardPostalCode

              If credit-card paymentMethod is used, the postal code inout by the caller or by the agent. For example, PaymentCardPostalCode=94109


              Note: Postal Code is not PCI data, so it can be clearly visible.

              PaymentCardType

              If credit-card paymentMethod used,

              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.

              Required

              The 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

              SecurityCode

              If credit-card paymentMethod is used, the security code input by the caller with all digits redacted. For example, SecurityCode=xxx

              Example 2
                    
                    
                    
                    
                    Example 3
                          
                          
                          
                          

                          Status

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

                          StatusCallback (Cancel/Complete)

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

                          Parameter

                          Description

                          DateUpdated

                          The date when the Pay session was last updated

                          ConnectorError

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

                          PayErrorCode

                          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

                          PaymentError

                          Payment error for failures. For example, card is declined

                          PaymentConfirmationCode

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

                          PaymentToken

                          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 - Token (one-time)

                          ProfileId

                          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

                          Result

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

                          Result

                          Result

                          Description

                          success

                          Twilio successfully captured the payment data and either tokenized or processed the payment

                          payment-connecter-error

                          Twilio Pay experienced an error communicating with Payment Gateway

                          caller-interrupted-with-star

                          Caller pressed * (star) key to interrupt the Pay session

                          caller-hung-up

                          Caller hung-up the call

                          validation-error

                          Invalid parameter value e.g. chargeAmount=”-0.5”

                          Rate this page:

                          Need some help?

                          We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

                                
                                
                                

                                Thank you for your feedback!

                                We are always striving to improve our documentation quality, and your feedback is valuable to us. How could this documentation serve you better?

                                Sending your feedback...
                                🎉 Thank you for your feedback!
                                Something went wrong. Please try again.

                                Thanks for your feedback!

                                Refer us and get $10 in 3 simple steps!

                                Step 1

                                Get link

                                Get a free personal referral link here

                                Step 2

                                Give $10

                                Your user signs up and upgrade using link

                                Step 3

                                Get $10

                                1,250 free SMSes
                                OR 1,000 free voice mins
                                OR 12,000 chats
                                OR more