Twilio Agent Assist Integration Guide

This guide covers agent-assisted payments using Twilio's Payments Subresource API. For automated IVR payments, see the IVR Integration Guide.

Overview

Agent-assisted payments let call center agents guide customers through payment collection. The agent controls the flow through a custom UI, but never sees or hears the actual card details - Twilio captures the data securely and sends it directly to your payment processor.

Key difference from IVR: Instead of the <Pay> TwiML verb, agent-assisted payments use the Twilio Payments Subresource API to give agents programmatic control over the payment flow.

Prerequisites

Complete the setup steps in the Introduction:

• Enable PCI Mode on your Twilio account
• Install the Shuttle Pay Connector

You'll also need:

• A backend service to proxy calls to the Twilio API (agents shouldn't have direct access to your Twilio credentials)
• A webhook endpoint to receive status callbacks during payment sessions

Twilio Payments API

Agent-assisted payments use the Twilio Payments Subresource API. All endpoints are relative to an active call:

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

The flow is:

1. Start session - Create a payment session attached to the call
2. Capture fields - Prompt the customer for each payment field
3. Complete or cancel - Finalize the transaction or abort

1. Start Payment Session

Call the Twilio Create Payment API to initialize a payment session.

POST /2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Payments.json

Twilio parameters:

Transaction types:

Shuttle parameters are passed as a JSON string in the Parameter field. See the Shuttle Pay Connector Reference for the full list. Common ones:

{
  "action": "PAYMENT",
  "save_card": "true",
  "alt_key": "INV-12345",
  "account_email": "[email protected]"
}

Example request:

curl -X POST "https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Payments.json" \
  -u "{AccountSid}:{AuthToken}" \
  -d "IdempotencyKey=unique-key-123" \
  -d "StatusCallback=https://your-server.com/webhooks/payment-status" \
  -d "PaymentConnector=shuttle-pay-connector" \
  -d "ChargeAmount=50.00" \
  -d "Currency=USD" \
  -d 'Parameter={"action":"PAYMENT","alt_key":"INV-12345"}'

The response includes a PaymentSid (e.g., PK123abc...) for subsequent operations.

2. Capture Payment Fields

Call the Twilio Update Payment API to prompt the customer for each field.

POST /2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Payments/{PaymentSid}.json

Example - capture card number:

curl -X POST "https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Payments/{PaymentSid}.json" \
  -u "{AccountSid}:{AuthToken}" \
  -d "Capture=payment-card-number"

When you trigger a capture:

1. Twilio plays an audio prompt to the customer
2. Customer enters digits on their phone keypad
3. Agent cannot hear the DTMF tones
4. Twilio sends a webhook to your StatusCallback with the result

The agent can capture fields in any order and re-capture if the customer makes a mistake.

3. Complete or Cancel

Once all required fields are captured, finalize the transaction:

Complete:

curl -X POST "https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Payments/{PaymentSid}.json" \
  -u "{AccountSid}:{AuthToken}" \
  -d "Status=complete"

Cancel:

curl -X POST "https://api.twilio.com/2010-04-01/Accounts/{AccountSid}/Calls/{CallSid}/Payments/{PaymentSid}.json" \
  -u "{AccountSid}:{AuthToken}" \
  -d "Status=cancel"

Webhooks

Agent Assist involves two separate webhook streams:

Twilio Status Callbacks

Twilio sends webhooks to your StatusCallback URL throughout the payment session. Use these to update the agent's UI in real-time.

On session completion, Twilio includes Shuttle fields (prefixed with PayConnector_):

For the full list of response fields, see the Shuttle Pay Connector Reference.

Shuttle Webhooks

Separately, Shuttle sends webhooks to your configured endpoint for payment events (PAYMENT.SUCCESS, PAYMENT.DECLINE, etc.). These are useful for:

• Reconciliation and downstream system updates
• Handling async gateway responses
• Backup if Twilio callbacks fail

These are the same webhooks used for IVR payments. See the Shuttle Pay Connector Reference for configuration.

Building the Agent Widget

Your widget needs to orchestrate the Twilio API calls and display status to the agent.

Getting the CallSid

The CallSid identifies the active Twilio call. How you get it depends on your platform:

• Twilio Flex: Available in the task context
• Custom softphone: Pass it when the call connects
• Third-party CCaaS: Check their docs for accessing call metadata

Payment Configuration

Before starting the session, the agent (or your application) configures the transaction. This maps to the parameters in the Start Payment Session call:

• Transaction type: Charge, tokenize, or both
• Amount and currency: Required for charges
• Reference: Your internal ID (alt_key parameter)

You can pre-fill these from your application context or let the agent enter them manually.

Field Capture Interface

Provide controls for the agent to trigger each capture and see the results:

1. Capture buttons - One for each field (card number, expiry, CVV, postal code). When clicked, your backend calls the Twilio Update Payment API with the corresponding Capture value.

2. Status display - Show the current state of each field:

   • Not started
   • Capturing (waiting for customer input)
   • Captured successfully
   • Error (validation failed)

3. Re-capture - Allow the agent to re-trigger any field if the customer needs to correct their input.

Your backend receives status callbacks from Twilio and pushes updates to the widget via WebSocket or polling.

Completion

Once all required fields show as captured:

• Complete button - Calls the Twilio API with Status=complete
• Cancel button - Calls the Twilio API with Status=cancel

Results

On completion, display or pass back to your system:

• PaymentConfirmationCode - Shuttle payment ID
• PayConnector_gateway_reference - Gateway transaction ID (for refunds, support queries)
• PayConnector_gateway_token - Saved card token (if applicable)

Error Handling

For decline types and meanings, see the Shuttle Pay Connector Reference.

Post-Payment Operations

After a successful payment, use the Shuttle API for refunds, captures, voids, and charging saved cards. See the Shuttle Pay Connector Reference.

References

• Twilio Payments Subresource API - Full API reference
• Twilio Agent-Assisted Payments Blog - Overview and use cases
• Twilio Flex Plugin Quickstart - If building for Twilio Flex
• Shuttle Pay Connector Reference - Parameters, responses, webhooks