Skip to content
Status

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 Twilio Agent Assist integration guide.

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.

Complete the setup steps in the Introduction:

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

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 tokenisation 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)
timeout No Seconds Twilio waits for the caller’s next key, both before the first digit of each entry and after the last (default: 5) - we recommend 30, or 8-10 if callers have their card ready first (see below)
maxAttempts No Attempts allowed for each entry, 1-3 (default: 1) - we recommend 3
statusCallback No URL for progress updates
description No Transaction description

Twilio uses the one timeout for two waits. It is how long Twilio waits for the first digit of each entry, and how long it waits after the last digit before it accepts the entry. Pressing # ends the entry straight away. Without it, the caller hears the full timeout of silence after every entry, including the expiry date and security code. Set maxAttempts="3" and choose one of these:

  • A long timeout, and ask for #. Set timeout="30" and end each prompt by asking the caller to press # (see Customising voice prompts). Callers have time to find their card, and those who press # move straight on. Anyone who doesn’t press # hears up to 30 seconds of silence after each entry.
  • Card ready first, then a short timeout. Ask callers to get their card ready before <Pay> starts, for example with a <Say> and a short <Pause>, then set timeout to 8-10 seconds. The pause after each entry is never longer than that, even for callers who don’t press #, though asking for # still helps. A caller who isn’t ready in time is prompted again, which uses one of their attempts.

Transaction types:

Type chargeAmount Shuttle action Result
Tokenisation 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.

Save a card for future use without charging:

<Pay
paymentConnector="shuttle-pay-connector"
action="https://yourapp.com/next_step"
timeout="30"
maxAttempts="3">
</Pay>
<Pay
paymentConnector="shuttle-pay-connector"
action="https://yourapp.com/next_step"
chargeAmount="29.99"
currency="usd"
postalCode="false"
timeout="30"
maxAttempts="3">
<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>

Hold funds for later capture:

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

ACH payments need the bank_account_type parameter, set to checking, savings or businessChecking, and the AVSName parameter. See ACH-specific parameters.

<Pay
paymentConnector="shuttle-pay-connector"
action="https://yourapp.com/next_step"
chargeAmount="19.99"
timeout="30"
maxAttempts="3">
<Parameter name="frequency" value="MONTHLY"/>
<Parameter name="occurrences" value="12"/>
<Parameter name="start_date" value="2027-01-01T00:00:00"/>
</Pay>
<Pay
paymentConnector="shuttle-pay-connector"
action="https://yourapp.com/payment_complete"
chargeAmount="149.99"
description="Premium Plan - Monthly"
timeout="30"
maxAttempts="3">
<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="jane.doe@example.com"/>
<Parameter name="metadata_plan" value="premium"/>
<Parameter name="metadata_billing_cycle" value="monthly"/>
</Pay>

Pass the cardholder’s billing address with billing_* parameters if your payment gateway performs address verification. The account_* parameters carry customer identity only - they do not include an address. See the Shuttle Pay connector reference for the full field list.

<Pay
paymentConnector="shuttle-pay-connector"
action="https://yourapp.com/payment_complete"
chargeAmount="49.99"
timeout="30"
maxAttempts="3">
<Parameter name="account_first_name" value="Jane"/>
<Parameter name="account_last_name" value="Doe"/>
<Parameter name="billing_line1" value="123 Main Street"/>
<Parameter name="billing_line2" value="Apt 4B"/>
<Parameter name="billing_line4" value="Springfield"/>
<Parameter name="billing_line5" value="62704"/>
<Parameter name="billing_line6" value="IL"/>
<Parameter name="billing_country" value="US"/>
</Pay>

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

End each prompt by asking the caller to press # (“pound” in the US, “hash” in the UK). With timeout="30", a caller who presses # moves straight on to the next step, and one who doesn’t hears 30 seconds of silence after each entry.

<Pay
paymentConnector="shuttle-pay-connector"
action="https://yourapp.com/next_step"
chargeAmount="29.99"
timeout="30"
maxAttempts="3">
<Prompt for="payment-card-number">
<Say>Please enter your card number using your phone keypad, then press pound</Say>
</Prompt>
<Prompt for="expiration-date">
<Say>Now enter the four digit expiration date, then press pound</Say>
</Prompt>
<Prompt for="postal-code">
<Say>Enter your billing zip code, then press pound</Say>
</Prompt>
<Prompt for="security-code">
<Say>Finally, enter the security code, then press pound</Say>
</Prompt>
<Prompt for="payment-processing">
<Say>One moment while we securely process your payment</Say>
</Prompt>
</Pay>

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 Tokenised 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 are sent from Shuttle to your backend, separately from Twilio’s callbacks, so you keep a record of every payment - IVR or Agent Assist - even when a call drops part way through. See the Shuttle Pay connector reference for events and configuration.

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

Was this page helpful?