Twilio Generic Pay Connector: How It Works and What It Means for Your PCI Scope

Twilio's Generic Pay Connector, generally available since 15 August 2023, lets you connect Twilio's <Pay> verb to any payment gateway by pointing it at an HTTPS endpoint you control. Twilio captures the card details on its PCI infrastructure, then POSTs them to your endpoint for processing.

That last part is the detail that matters. The payload your endpoint receives contains the full, cleartext card number and CVV. Whoever hosts that endpoint is handling cardholder data.

Quick answer: the Generic Pay Connector is the right tool if you are a payment gateway or processor with an existing PCI-certified platform, which is exactly who Twilio built it for. If you are a merchant or a software platform and you host the endpoint on your own infrastructure, that infrastructure starts storing, processing, or transmitting full card data, which pulls it into full PCI DSS scope (SAQ D territory rather than SAQ-A). A hosted, PCI-certified connector such as Shuttle's avoids this entirely: card data flows from Twilio to the connector to your gateway, and your systems only ever see redacted results.

This guide explains how the Generic connector works, what you would actually be building and attesting to, and how the hosted alternative compares.

How the Generic Pay Connector Works

The Generic Pay Connector is one of the connectors available for Twilio <Pay>, alongside gateway-specific connectors like Stripe and hosted third-party connectors like Shuttle. Its job is deliberately open-ended: instead of integrating a named gateway, Twilio sends the captured payment data to an Endpoint URL you configure. Twilio's own setup docs describe it plainly: "Enter the ENDPOINT URL for your payment processor's infrastructure. This is where Twilio will send your customers' payment information."

The mechanics:

1. **Capture.** Your call flow triggers `<Pay>`. The caller enters their card details via DTMF keypad input, captured inside Twilio's PCI-compliant environment with tones suppressed.

2. Delivery. Twilio sends the payment data to your configured Endpoint URL as an HTTPS POST, authenticated with HTTP Basic Auth credentials you supply when setting up the connector.

3. Processing. Your endpoint takes that data, calls your payment gateway's API, and returns the result to Twilio.

What the payload contains

This is not a token or a redacted reference. Twilio's own tutorial example shows the POST body carrying cardnumber (4111111111111111), cvv (333), expiry_month, expiry_year and postal_code, alongside transaction_id, amount, currency_code, method, description and any custom parameters. For ACH payments, the payload carries bankaccountnumber and routingnumber.

Custom parameters are worth a note: the <Parameter> noun, which lets you attach custom fields to a <Pay> request, is documented only for the Generic Pay Connector. If you rely on it, you are relying on Generic-connector-specific behaviour.

The endpoint contract

Your endpoint must implement Twilio's expected interface: accept the POST and respond with {"charge_id": ...} for an immediate charge, or {"token_id": ...} when tokenising a card for later use. (Twilio previously specified separate /charge and /tokenize endpoints; these were deprecated in favour of a single root endpoint that handles both.)

The TEST-to-LIVE gate

Generic connectors start in TEST mode, and you cannot flip them to LIVE through the Twilio Console. Per Twilio's docs, going live requires contacting Twilio Support and submitting:

• the latest, non-expired Attestation of Compliance (AOC) from your payment gateway,

• the gateway URL, and

• confirmation that you have reviewed the downstream gateway's PCI compliance.

Once in LIVE mode, the gateway URL becomes immutable. That review process exists for a reason: Twilio is about to send real card data to whatever sits at that URL.

What You Are Signing Up To Build

If you choose the Generic connector as a merchant or platform, "configure an endpoint URL" understates the project. In practice you are building and operating a small piece of payment infrastructure:

• The receiving endpoint. An always-available HTTPS service that authenticates Twilio's Basic Auth, parses the payload, and never logs, caches, or mishandles the card data it receives.

• The gateway integration. Code that maps Twilio's payload to your gateway's charge and tokenisation APIs, including currency handling, decline mapping, and 3DS or gateway-specific quirks.

• Error handling and idempotency. Retried POSTs must not double-charge callers. Timeouts, gateway outages, and partial failures all need defined behaviour, because a live phone call is waiting on the response.

• The compliance artefacts. A current AOC for your downstream gateway, the Twilio Support go-live process, and the operational reality that your gateway URL is frozen once LIVE. Changing gateways later means a new connector and a new go-live review.

None of this is a criticism of the design. Twilio is explicit about the intended builder: "the payment processor/gateway will need to write custom, PCI-compliant code to work with Twilio's Generic Pay Connector." Twilio's tutorial even ships a mock server for development and labels it as not PCI compliant and not production-ready. The framework assumes the party behind the endpoint already runs a certified payment platform.

It is also worth being clear about what <Pay> does and does not do for your compliance position. Twilio's Pay legal terms state that using <Pay> "will not make Customer PCI-DSS compliant", with responsibilities divided per the Twilio PCI-DSS Responsibility Matrix. Twilio secures the capture. What happens after the POST leaves Twilio is on you.

The PCI Scope Question

Here is the part every merchant and platform team should price in before writing any code. What follows is standard PCI DSS reasoning, not a Twilio statement, and your acquirer or QSA makes the final call on your validation requirements.

Under PCI DSS, any system component that stores, processes, or transmits cardholder data is in scope. A merchant-owned endpoint receiving full PAN and CVV over the internet is not adjacent to the cardholder data environment (CDE). It *is* the CDE, along with the network segments, servers, logging pipelines, and admin access paths connected to it. See what PCI scope covers for the full definition.

That typically means full-scope assessment territory: SAQ D-Merchant, or a full Report on Compliance (RoC) with a QSA depending on your card volume. In concrete terms:

• network segmentation to isolate the CDE,

• vulnerability management and patching programmes,

• access control, logging, and log review,

• quarterly ASV scans and penetration testing,

• annual reassessment of all of it.

Contrast that with the hosted-connector model, where card data flows from Twilio to a PCI-certified connector to your gateway, and your systems only ever receive redacted results (last four digits, card brand, transaction reference). That is SAQ-A territory, the lightest self-assessment, because cardholder data never touches your environment.

For a deeper treatment of how this plays out with Twilio specifically, see Twilio PCI Compliance: Payments Without Handling Card Data, and for what Level 1 service provider status actually involves, see PCI Compliance for Service Providers.

Who Should Use the Generic Connector

An honest list, because the Generic connector is a legitimate and useful tool for its intended audience:

• Payment gateways and processors integrating themselves. If you run a PCI-certified payment platform and want to offer your merchants voice payments through Twilio, the Generic connector is the mechanism Twilio built for you. You already hold the AOC, you already operate a CDE, and the custom endpoint is a thin adapter onto your existing APIs.

• Teams with an existing PCI DSS Level 1 environment who want full control. If your organisation already maintains a Level 1 assessed environment for other reasons and has the engineering appetite to own the endpoint, the incremental compliance burden is real but bounded.

If neither describes you, the calculus changes. Building the endpoint is days of work. Operating it inside a full-scope PCI programme is a permanent annual cost, and it exists solely to move card data you never wanted to touch.

There is also little or no per-transaction saving for doing it yourself: Twilio prices the Generic Pay Connector at $0.15 to $0.20 per request (its Console catalogue and its Pay Connector pricing page show slightly different figures), in the same range as the Shuttle connector's $0.20. The build-your-own path saves at most a few cents per transaction and adds the endpoint, the gateway integration work, and the PCI scope on top.

The Hosted Alternative: Shuttle

Shuttle's Pay Connector, live on Twilio since December 2023 and named in Twilio's <Pay> TwiML documentation among the connectors available in the IE1 and AU1 regions, is the hosted version of what the Generic connector asks you to build. Shuttle is a PCI DSS Level 1 Service Provider and operates the endpoint, the gateway integrations, and the compliance surface, so you do not have to.

What changes in practice:

1. Install from the Twilio Marketplace. No custom endpoint, no Basic Auth credentials to mint, no Twilio Support go-live review.

2. **Add your gateway credentials as payment profiles.** Shuttle connects to 30+ gateways through one connector: Stripe, Adyen, Worldpay, Checkout.com, Cybersource, and more.

3. Point `<Pay>` at `shuttle-pay-connector`. Your TwiML or Studio flow works the same way; only the paymentConnector attribute differs.

Card data flows from Twilio to Shuttle to your gateway. Your webhook receives the redacted result: last four, brand, transaction reference. Your scope stays at SAQ-A.

Beyond the compliance position, the hosted model adds things a single custom endpoint does not:

• Multi-PSP routing by merchant, region, amount, or failover, configured in the dashboard rather than rebuilt in code. (Recall that the Generic connector's gateway URL is immutable in LIVE mode; changing gateways means a new connector.)

• Cross-channel tokens. Tokenise a card once on a call and reuse it across web, mobile, voice, and payment links.

• **Custom parameters, documented.** Shuttle supports the `<Parameter>` noun directly: customer details via `account_` names (first name, last name, email), your own reference data via `metadata_` names, plus `action="AUTH"` for pre-authorisation holds and `frequency`/`occurrences` for recurring payments set up in the call itself. See Shuttle's Twilio integration docs.

Pricing is $0.20 per successful transaction for the first 50,000 per month, tiering down to $0.05 above 1 million, with no setup fees or monthly minimums.

For the broader landscape of connector options, see Twilio Pay Connectors: How to Connect Any Payment Gateway, and for a gateway-specific walkthrough, the Stripe Pay Connector guide.

Migrating from the Generic Connector to Shuttle

If you already run a Generic connector endpoint, migration is a configuration exercise rather than a rebuild:

1. Map your current gateway to a Shuttle payment profile. Same gateway account, same merchant credentials, entered once in the Shuttle dashboard.

2. Replicate custom parameters. Anything you pass via <Parameter> today moves to Shuttle profile configuration and webhook payloads.

3. Run both in TEST. Shuttle profiles support test mode, so you can verify charges and tokenisation end to end alongside the existing connector.

4. Swap the `paymentConnector` attribute. One TwiML change per call flow. Nothing else in your <Pay> configuration needs to move.

5. Decommission the endpoint and shrink your CDE. Retire the receiving service, its credentials, and its logging paths.

That last step is not just cleanup. Removing the only internet-facing system that handles PAN shrinks your cardholder data environment, which is itself a compliance win at your next assessment: less to segment, less to scan, and potentially a lighter SAQ altogether. Contact centre teams running agent-assisted flows can see how this fits the wider picture in our contact centre payments guide.

Generic Pay Connector FAQ

What is the Twilio Generic Pay Connector? It is a <Pay> connector, generally available since August 2023, that sends payment data captured by Twilio to an HTTPS endpoint you configure, instead of to a pre-integrated gateway. Twilio designed it so payment processors and gateways can write custom, PCI-compliant code to connect their own platforms to Twilio Pay.

Does the Generic Pay Connector send full card numbers? Yes. Twilio's tutorial payload shows the full card number and CVV in cleartext (for example cardnumber: 4111111111111111, cvv: 333), plus expiry, postal code, amount, and any custom parameters. ACH payloads carry the full bank account and routing numbers.

Is the Generic Pay Connector PCI compliant? Twilio's capture side is. The endpoint side is whatever you make it: Twilio's legal terms state that using <Pay> "will not make Customer PCI-DSS compliant", and going LIVE requires submitting your gateway's Attestation of Compliance to Twilio Support. Twilio's own tutorial mock server is explicitly labelled not PCI compliant and not production-ready.

What SAQ do I need if I host the endpoint myself? As standard PCI DSS reasoning (confirm with your acquirer or QSA): an endpoint receiving full PAN and CVV puts your infrastructure in the CDE, which typically means SAQ D-Merchant or a full RoC depending on card volume. With a hosted PCI-certified connector, where your systems only see redacted results, SAQ-A typically applies.

Can I use multiple gateways with the Generic connector? Not through one connector: the gateway URL becomes immutable once the connector is LIVE, so each gateway means a separate connector and go-live review. Shuttle's hosted connector routes to 30+ gateways from a single <Pay> integration, with routing rules by merchant, region, amount, or failover.

How do I switch from the Generic connector to another connector? Change the paymentConnector attribute in your <Pay> TwiML or Studio widget to the new connector (for example shuttle-pay-connector) once it is installed and configured. Your call flows otherwise stay the same, and you can then decommission your custom endpoint.

Related Reading

• Twilio Pay Connectors: How to Connect Any Payment Gateway covers the full connector landscape and multi-PSP routing

• Twilio PCI Compliance: Payments Without Handling Card Data explains how to keep your scope at SAQ-A

• PCI Compliance for Service Providers breaks down Level 1 requirements and scope reduction

• How the Twilio Stripe Pay Connector Works looks at Twilio's built-in Stripe option

• DTMF Payments: Clamping, Masking and PCI Compliance covers how keypad capture stays out of recordings

• Contact Centre Payments is the hub for agent-assisted and IVR payment flows

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

*Skip the custom endpoint and the full-scope PCI programme. Shuttle's hosted Pay Connector is PCI DSS Level 1, connects 30+ gateways, and keeps your systems at SAQ-A. Install on Twilio or book a discovery call.*