How to Switch Twilio Pay Connectors Without Breaking Your Call Flow

Quick answer: switching Twilio Pay Connectors is a one-attribute change. The connector is selected per-request by the paymentConnector attribute on the <Pay> verb (or the connector name in the Agent Assist Payments API call). The real work is the checklist around it: saved card tokens do not port between connectors, custom <Parameter> support differs, and webhook result fields vary slightly. Because Twilio lets you install multiple connectors side by side, you can run old and new in parallel and cut over.

This guide covers what actually changes, the full migration checklist, and the two most common starting points: the Stripe connector and a self-built Generic connector.

What Actually Changes (and What Does Not)

Twilio designed <Pay> so that the connector is a routing decision, not an architecture decision. That is good news for anyone who has hit a capability wall on their current connector.

What stays the same:

• Your <Pay> TwiML structure. chargeAmount, currency, action, statusCallback, prompts, and input handling are all connector-agnostic. None of it changes.

• Your call flow. IVR logic, agent scripting, and DTMF capture behave identically. Twilio handles the capture regardless of which connector processes the payment.

• Your Twilio account and phone numbers. Nothing at the account level moves.

What changes per connector, and needs planning:

• Saved card tokens. Tokens are not portable. A Stripe Token or PaymentMethod id lives in Stripe's vault and was created through the Stripe connector; tokens created via a different connector stay with the gateway that stored them. If you charge repeat customers against stored tokens, this is the biggest item on your checklist.

• Custom <Parameter> support. The Stripe connector supports an undocumented metadata_ prefix and a CustomerPhone parameter on reusable tokens, per its Marketplace listing. Shuttle's connector documents its parameters: account_* for customer details, metadata_* for pass-through data, action=AUTH for authorise-now-capture-later, and frequency for recurring setup.

• Webhook result fields. The core result payload is consistent, but some fields differ slightly per connector. ProfileId, for example, means different things depending on the connector, per Twilio's <Pay> documentation. Your result handler needs a quick review.

• Twilio's per-transaction fee. Twilio bills the Stripe connector at $0.15 per successful transaction for the first 10,000 a month (tiering down at volume) and Shuttle from $0.20, falling with volume, and CardConnect moved to usage-based billing in October 2025. Shuttle also charges $49 per live instance per month. Factor the delta into your business case alongside what you gain.

One attribute to change, four things to plan. Here is the sequence.

The Migration Checklist

1. Install the new connector alongside the old one. The Twilio Console catalogue supports multiple installed connectors, and Twilio's docs describe creating multiple instances of a connector. Install Shuttle's Pay Connector from the Twilio Marketplace without touching your existing one. Nothing changes in production yet.

2. Recreate your configuration on the new connector. For Shuttle, that means adding your gateway credentials as payment profiles in the Shuttle dashboard. Your existing gateway account stays exactly as it is: if you process through Stripe today, Shuttle routes to that same Stripe account, and your gateway fees are unchanged. You are swapping the bridge, not the bank.

3. Map your custom parameters. Audit every <Parameter> in your TwiML. Stripe's undocumented metadata_ workaround maps cleanly to Shuttle's documented metadata_* parameters, so your pass-through data survives. While you are in there, consider adding account_* parameters to pass customer details, or action=AUTH if you want authorise-now-capture-later.

4. Plan for saved tokens. Stored cards do not transfer, so pick a strategy per customer segment:

   • Run both connectors in parallel. Keep charging existing tokens through the old connector while all new payments (and new tokenisations) go through the new one. Retire the old connector once the token base has rolled over.

   • Re-capture on the next call. The next time a repeat customer calls, take card details fresh through the new connector and store the new token.

   • Send a payment link to re-capture the card. Push customers a hosted payment link so they can re-enter card details on their own time, no call needed.

5. Update your webhook handling. Review your action and statusCallback handlers against the new connector's result fields. Most fields carry over, but check anything you parse from ProfileId or connector-specific confirmation codes, and update your transaction lookup logic to point at the new connector's references.

6. Test end to end in sandbox. Shuttle supports test mode via sandbox gateway credentials, so you can run the full flow with test cards: capture, charge, webhook, and any post-payment operations like refunds, captures, and voids via the Shuttle API.

7. Cut over. Change the paymentConnector attribute in your TwiML, or the connector name in your Agent Assist API call. Because the attribute is evaluated per request, the change takes effect on the very next call. Calls already in progress on the old connector complete normally.

8. Monitor, then uninstall. Watch success rates and webhook results for a week or two. Once you are confident (and any parallel-run token strategy has completed), uninstall the old connector from the Console.

Switching From the Stripe Connector

The most important thing to understand: your Stripe account survives the switch. Shuttle connects to Stripe as one of its 30+ supported gateways, so you add your Stripe credentials as a Shuttle payment profile and transactions keep settling into the same Stripe account at the same Stripe fees. Only the connector layer changes.

What you gain is the capability set the Stripe connector does not offer: documented custom parameters, authorise-and-capture-later, multi-gateway routing, and post-payment operations (refunds, captures, voids) through the Shuttle API. The full comparison is in Twilio Stripe Pay Connector: Capabilities and Limits.

The one real migration cost is tokens. Stripe PaymentMethod ids created through the Stripe connector stay usable in Stripe itself, but they were created via that connector's flow, so plan your repeat-customer strategy per step 4 above.

Switching Off a Self-Built Generic Connector

If you built your own connector on Twilio's Generic Pay Connector framework, you are carrying two burdens a pre-built connector removes: the endpoint and the compliance scope.

The Generic connector's gateway URL is immutable in LIVE mode, and going live required submitting an Attestation of Compliance to Twilio Support. That endpoint receives cardholder data, which means it sits inside your PCI cardholder data environment, with everything that implies for your assessments.

Switching to Shuttle means decommissioning that self-hosted endpoint entirely. Card data flows from Twilio to Shuttle (a PCI DSS Level 1 Service Provider) and on to your gateway, never touching your infrastructure. Your cardholder data environment shrinks, which is a concrete win at your next assessment. Merchants complete SAQ-A, the lightest PCI self-assessment; platforms complete SAQ-D. Everyone taking card payments has to be PCI compliant, and your acquirer confirms which form applies to you. The full background is in Twilio Generic Pay Connector: Build vs Buy.

Rollback Plan

Keep the old connector installed until you are confident. Because the connector is selected per request, rolling back is the same one-attribute change in reverse: point paymentConnector back at the old connector name and the next call uses it. No reinstallation, no reconfiguration, no waiting.

This is also why the parallel-run strategy is low risk. Both connectors sit installed side by side, both fully configured, and your TwiML decides which one handles each payment. You control the pace of the cutover completely.

Switching Pay Connectors FAQ

Can I run two Twilio Pay Connectors at once? Yes. The Twilio Console supports multiple installed connectors, and each <Pay> request selects its connector via the paymentConnector attribute. Running old and new in parallel during migration is the standard zero-downtime approach.

Do saved cards transfer between Pay Connectors? No. Saved cards stay with the gateway that stored them, so they do not port. Plan for repeat customers by running the old connector in parallel until tokens roll over, re-capturing card details on the next call, or sending a payment link to re-capture the card.

Do I need to change my Twilio call flow? Only the paymentConnector attribute (or the connector name in your Agent Assist API call). The rest of the <Pay> structure, including chargeAmount, currency, action, and statusCallback, is connector-agnostic.

Will my Stripe account still work after switching? Yes. If you switch to Shuttle, you add your existing Stripe account as a payment profile and Shuttle routes transactions to it. Settlement, reporting, and your Stripe fees are unchanged. Only the connector between Twilio and Stripe changes.

How long does switching take? Installing and configuring the new connector is a short job, and the cutover takes effect call by call because the attribute is evaluated per call. The overall timeline is set by your token strategy: if you have no stored cards, you can cut over as soon as the new connector is set up and tested; if you charge repeat customers, plan for a parallel-run period.

Related Reading

• Twilio Pay Connectors: How to Connect Any Compatible Payment Gateway: the complete guide to Twilio Pay Connectors and multi-PSP routing

• Twilio Stripe Pay Connector: Capabilities and Limits: what the Stripe connector does and where it stops

• Twilio Generic Pay Connector: Build vs Buy: what building your own connector really involves

• Twilio Pay Error Codes Explained: diagnosing failed payments during and after migration

• Twilio PCI Compliance: Payments Without Handling Card Data: how to keep your PCI scope limited

• Twilio Pay: Connect Any Compatible Payment Gateway to Twilio: all supported gateways, pricing, and setup

Switch to Shuttle's Pay Connector: 30+ gateways, PCI DSS Level 1, $49 per live instance per month, plus from $0.20 per transaction, falling with volume, billed through your Twilio account. Install on Twilio or book a discovery call.