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), so pointing your call flow at a new connector takes seconds. 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 with zero downtime.
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, Studio flows, agent scripting, and DTMF capture behave identically. Twilio handles capture and tone suppression 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 live in that connector or gateway's vault. 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 routing to a specific payment profile, `metadata_
for pass-through data,action=AUTHfor authorise-now-capture-later, andfrequency` 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, Shuttle at $0.20, and CardConnect moved to usage-based billing in October 2025. 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
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.
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.
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 if you route to more than one gateway profile, oraction=AUTH` if you want authorise-now-capture-later.
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-vault. Push customers a hosted payment link so they can re-enter card details on their own time, no call needed.
Update your webhook handling. Review your
actionandstatusCallbackhandlers against the new connector's result fields. Most fields carry over, but check anything you parse fromProfileIdor connector-specific confirmation codes, and update your transaction lookup logic to point at the new connector's references.
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.
Cut over. Change the
paymentConnectorattribute in your TwiML, or the connector name in your Studio flow's Pay widget or 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. Zero downtime.
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 vaulted 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: you qualify for SAQ-A, the lightest self-assessment. 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. Tokens live in the vault of the gateway or connector that created 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-vault.
Do I need to change my Twilio call flow? Only the paymentConnector attribute (or the connector name in your Studio Pay widget or 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 typically takes under an hour, and the cutover itself is instant because the attribute is evaluated per call. The overall timeline is set by your token strategy: if you have no stored cards, you can switch same-day; if you charge repeat customers, plan for a parallel-run period.
Related Reading
Twilio Pay Connectors: How to Connect Any 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 at SAQ-A
Twilio Pay: Connect Any Payment Gateway to Twilio: all supported gateways, pricing, and setup
*Switch to Shuttle's Pay Connector with zero downtime: 30+ gateways, PCI DSS Level 1, $0.20 per successful transaction. Install on Twilio or book a discovery call.*