Twilio IVR Integration Guide

This guide covers how to integrate Shuttle payments into your Twilio IVR workflows using the <Pay> TwiML verb for self-service payment collection. For agent-assisted payments, see the Agent Assist Integration Guide.

Overview

The Twilio <Pay> verb enables automated DTMF payment collection during phone calls. Customers enter their card details using their phone keypad in response to voice prompts, without agent involvement.

Prerequisites

Complete the setup steps in the Introduction:

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

Twilio `<Pay>` Verb

The <Pay> verb is added to your TwiML to collect payment details. See the Twilio Pay documentation for the full reference.

Twilio parameters:

Parameter	Required	Description
`paymentConnector`	Yes	Your connector name (e.g., `shuttle-pay-connector`)
`action`	Yes	URL for next TwiML instructions after payment
`chargeAmount`	No	Amount to charge - omit for tokenization only
`currency`	No	ISO currency code, lowercase (default: `usd`)
`paymentMethod`	No	`credit-card` or `ach-debit` (default: `credit-card`)
`postalCode`	No	AVS postal code collection (default: `true` for US/CA)
`statusCallback`	No	URL for progress updates
`description`	No	Transaction description

Transaction types:

Type	chargeAmount	Shuttle `action`	Result
Tokenization	Omit	-	Card saved, no charge
Payment (capture)	Set amount	`PAYMENT`	Card charged immediately
Payment (auth only)	Set amount	`AUTH`	Funds held, capture later
Payment + save card	Set amount	Include `save_card=true`	Card charged and saved

Shuttle parameters are passed as <Parameter> elements within the <Pay> verb. See the Shuttle Pay Connector Reference for the full list.

Examples

Card Tokenization

Save a card for future use without charging:

<Pay
  paymentConnector="shuttle-pay-connector"
  action="https://yourapp.com/next_step">
</Pay>

Standard Card Payment

<Pay
  paymentConnector="shuttle-pay-connector"
  action="https://yourapp.com/next_step"
  chargeAmount="29.99"
  currency="usd"
  postalCode="false">
  <Parameter name="save_card" value="true"/>
  <Parameter name="alt_key" value="INV-12345"/>
  <Prompt for="payment-processing">
    <Say>Please wait while we process your payment</Say>
  </Prompt>
</Pay>

Pre-Authorization

Hold funds for later capture:

<Pay
  paymentConnector="shuttle-pay-connector"
  action="https://yourapp.com/next_step"
  chargeAmount="99.99">
  <Parameter name="action" value="AUTH"/>
</Pay>

ACH Payment

<Pay
  paymentConnector="shuttle-pay-connector"
  action="https://yourapp.com/next_step"
  chargeAmount="49.99"
  paymentMethod="ach-debit"
  bankAccountType="consumer-checking">
  <Parameter name="AVSName" value="John Smith"/>
  <Prompt for="payment-processing">
    <Say>Processing your bank transfer</Say>
  </Prompt>
</Pay>

Recurring Payment

<Pay
  paymentConnector="shuttle-pay-connector"
  action="https://yourapp.com/next_step"
  chargeAmount="19.99">
  <Parameter name="frequency" value="MONTHLY"/>
  <Parameter name="occurrences" value="12"/>
  <Parameter name="start_date" value="2024-01-01T00:00:00"/>
</Pay>

With Full Traceability

<Pay
  paymentConnector="shuttle-pay-connector"
  action="https://yourapp.com/payment_complete"
  chargeAmount="149.99"
  description="Premium Plan - Monthly">
  <Parameter name="alt_key" value="SUB-2024-001"/>
  <Parameter name="account_crm_key" value="cus_123456"/>
  <Parameter name="account_first_name" value="Jane"/>
  <Parameter name="account_last_name" value="Doe"/>
  <Parameter name="account_email" value="[email protected]"/>
  <Parameter name="metadata_plan" value="premium"/>
  <Parameter name="metadata_billing_cycle" value="monthly"/>
</Pay>

Customizing Voice Prompts

Customize the messages spoken to callers using the <Prompt> element. See Twilio's Prompt documentation for all prompt types.

<Pay
  paymentConnector="shuttle-pay-connector"
  action="https://yourapp.com/next_step"
  chargeAmount="29.99">
  <Prompt for="payment-card-number">
    <Say>Please enter your card number using your phone keypad</Say>
  </Prompt>
  <Prompt for="expiration-date">
    <Say>Now enter the expiration date</Say>
  </Prompt>
  <Prompt for="security-code">
    <Say>Finally, enter the three digit security code</Say>
  </Prompt>
  <Prompt for="payment-processing">
    <Say>One moment while we securely process your payment</Say>
  </Prompt>
</Pay>

Tip: Use pre-recorded audio with <Play> instead of <Say> for a more polished experience.

Handling Responses

Twilio sends a POST request to your action URL with the payment results.

Important: Always check PayConnector_payment_status - Twilio may return Result: "success" even when the payment failed.

Twilio fields:

Field	Description
`Result`	Twilio status code
`PaymentCardNumber`	Masked card number
`PaymentCardType`	Card brand (visa, mastercard, etc.)

Shuttle fields (prefixed with PayConnector_):

Field	Description
`PayConnector_payment_status`	Primary status - always check this
`PayConnector_gateway_reference`	Gateway transaction ID
`PayConnector_gateway_token`	Tokenized card (when `save_card=true`)
`PaymentConfirmationCode`	Shuttle payment ID

For the complete list of response fields, status values, and example responses, see the Shuttle Pay Connector Reference.

Shuttle Webhooks

Shuttle sends webhooks to your configured endpoint for payment events. These are separate from Twilio's callbacks - they're sent from Shuttle to your backend for reliable payment tracking.

Use Shuttle webhooks for:

Disconnected calls during payment
Gateway timeouts
Held transactions requiring review
Scheduled/recurring payment updates

These webhooks fire for all payments processed through the Shuttle Pay Connector, whether initiated via IVR or Agent Assist.

See the Shuttle Pay Connector Reference for webhook events and configuration.

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 Pay Documentation - Full <Pay> verb reference
Twilio Prompt Documentation - Voice prompt customization
Shuttle Pay Connector Reference - Parameters, responses, webhooks
Demo Application Source