Vortex is a PCI-compliant, API-first middleware layer that enables AI voice agents (Vapi, Retell, Custom WebSockets) to securely process credit card payments mid-conversation via DTMF keypad inputs.
By intercepting an active telephony session, Vortex captures secure keypad inputs, tokenizes the sensitive data directly via Stripe (minimizing your infrastructure's PCI scope), and returns a structured event back to your AI agent—allowing the conversation to seamlessly resume with full context of the payment outcome.
- PCI Scope Minimization:
pciCompliance="true"is strictly enforced on Twilio<Gather>. Raw card data is processed purely in-memory and tokenized instantly via Stripe. It never touches the database or terminal logs. - Robust Telephony State Machine: Built-in 3-strike retry loop handles user input errors natively before hanging up.
- Multi-Tenant Ready: Includes a Clerk-protected Developer Dashboard where you can generate secure, hashed API keys and monitor your Organization's transactions.
- Stripe Connect Integration: Uses Destination Charges, allowing platform operators to collect application fees seamlessly.
- HMAC Signed Webhooks: Dispatches secure
payment.succeededorpayment.failedwebhooks back to the parent AI system to resume the conversation state.
- Framework: Next.js 14 (App Router)
- Language: TypeScript (Strict)
- Database: PostgreSQL (Supabase) via Prisma ORM
- UI/Components: Tailwind CSS & shadcn/ui
- Auth: Clerk
- Telephony: Twilio TwiML
- Payments: Stripe API
- Node.js (v18+)
- A Stripe account (Test mode is fine)
- A Twilio account
- A Clerk account
- A Supabase PostgreSQL database
You will need to configure both .env and .env.local to securely hold your keys.
.env (For Prisma Database Configuration):
DATABASE_URL="postgresql://postgres:[password]@aws-0-pooler.supabase.com:5432/postgres".env.local (For Next.js App Environment):
# Stripe (Use sk_test_mock for local webhook testing without a real key)
STRIPE_SECRET_KEY="sk_test_..."
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY="pk_test_..."
# Twilio
TWILIO_ACCOUNT_SID="..."
TWILIO_AUTH_TOKEN="..."
# Clerk
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY="pk_test_..."
CLERK_SECRET_KEY="sk_test_..."
# Webhook Secret (for your AI agents)
VORTEX_WEBHOOK_SECRET="your_secure_random_string"
# Base URL for local testing (e.g., ngrok)
NEXT_PUBLIC_APP_URL="http://localhost:3000"# Install dependencies
npm install
# Push the Prisma schema to your database
npx prisma db push
# Run the development server
npm run devThe Developer Dashboard is now accessible at http://localhost:3000/dashboard.
The entry point for your AI Agent to handoff a call for payment processing.
Headers:
x-api-key: vtx_live_your_api_key
Body:
{
"call_sid": "CA1234567890abcdef...", // The active Twilio Call SID
"amount": 1500, // Amount in cents ($15.00)
"currency": "usd",
"callback_url": "https://your-ai-agent.com/webhooks/vortex"
}Response:
Returns a redirect_url (pointing to Vortex/api/twilio/gather) that your AI agent should execute a TwiML <Redirect> to.
Testing the full Twilio TwiML flow locally can be tedious. To make it easy, this project includes a run_test.ps1 PowerShell script that simulates an end-to-end payment flow using mocked Stripe processing without needing a real phone line.
- Get an API Key: Generate a new API key from the Developer Dashboard.
- Update the Script: Open
run_test.ps1and replace the$apiKeyvariable at the top with your new key. - Run the Script:
.\run_test.ps1
- Verify: Check your Dashboard! You should see a successful transaction for $99.00!
Vortex is explicitly designed to handle DTMF payments while minimizing PCI DSS compliance burdens. By utilizing Twilio's PCI compliance flags and performing strictly in-memory tokenization against Stripe's backend Tokens API, the system ensures that Primary Account Numbers (PAN) and CVVs never touch persistent storage or application logs.