ringup-vapi-init

Add card-on-file payments to a Vapi voice agent. Returning callers are recognized by phone number and pay with their saved card in one sentence; charges settle on the merchant's own payment processor. You write no payment prompt and configure no models, transcribers, or languages: the payment step inherits everything from your agent.

Every element of what this CLI provisions was validated on live voice calls (2026-07-06), end to end, on two verticals. Evidence record: voice-platforms/vapi/KNOWLEDGE.md.

Commands

npx ringup-vapi-init test       talk to a finished demo first: pick a vertical (food, auto
                                parts, booking, insurance), get a fully wired demo squad and
                                a try-saying script; `test --clean` removes it
npx ringup-vapi-init            provision: builds everything, touches NOTHING you own
npx ringup-vapi-init stage      rehearse on a private test number: a disposable twin of your
                                agent with payments wired in, on a free canary line; your
                                real agent and number stay untouched
npx ringup-vapi-init go-live    the consented switch: points your number at the squad, THEN
                                makes the two changes (that order keeps mid-switch callers on
                                your current flow), deletes the rehearsal rig
npx ringup-vapi-init check      verifies the wiring from the API (15 assertions)
npx ringup-vapi-init rollback   reverses go-live exactly, your number included

Provision asks two things and nothing else: your Vapi private key (hidden input, used only for these API calls, never stored) and what to add payments to:

• (a)ssistant: pick your agent; the CLI assembles the squad around it.
• (s)quad: pick the squad, then pick which member confirms the order.
• (m)anual: provisions only the Ringup pieces and prints the wiring steps, for platforms that manage their own squads and templates. RINGUP_INIT_RESULT (last line, JSON) is machine-readable for provisioning scripts.

You are never asked for a business name, payment policy, model, transcriber, or language. The business is identified from the number the call comes in on; the policy is a merchant setting served by Ringup per purchase; everything else is inherited from your agent.

What provision creates (new objects only)

| Object | What it does | |---|---| | Payment member | Silently checks whether payment is needed for THIS purchase, then takes it (or says nothing at all). Inherits your agent's voice, model, and transcriber. | | Wrap-up member | YOUR agent in wrap-up mode (its prompt verbatim, only the Task replaced): announces success, reads back the payment confirmation number, thanks and ends the call. | | Five ringup_* tools | payment_policy / identify / charge / payment_status / send_link as static apiRequest tools against Ringup's REST face. Static config: nothing is fetched at handoff time. Caller and merchant resolve server-side from trusted headers; the model never types either. | | Handoff tool | The validated shape (required destination enum, "One moment." transition, neutral failure line). | | A new squad | Your agent (referenced live, untouched) -> payment -> wrap-up. |

Your assistant is byte-for-byte unmodified after provision, and the squad carries no traffic.

Stage, go-live, and rollback

stage builds a disposable rehearsal rig: a byte-copy twin of your confirming member with the two go-live changes baked in, a three-member rehearsal squad (twin -> payment -> wrap-up), and a free canary number pointed at it. Call the canary and hear exactly what your customers are about to hear; re-run stage after any fix. Nothing you own changes. Only the delta go-live introduces is rehearsed: your other members and hops run identically before and after, so they are not copied.

go-live does two things IN THIS ORDER, after showing them and asking once: points your number(s) at the squad, then makes exactly two changes to your assistant (append the handoff tool to its toolIds, append one line to its prompt). Number-first matters: a caller landing in the seconds between simply gets your current payment-free flow, while the reverse order strands callers with an agent reaching for a payment step that is not there yet (live-tested). It records where each number pointed, deletes the rehearsal rig (or keeps it as a permanent test line if you prefer), and rollback reverses everything: the two changes byte-for-byte and each number back to its exact prior destination. Choices are remembered in ~/.ringup/vapi.json, so the lifecycle commands need no flags; flags override for CI.

The call flow (every call, every merchant)

your agent takes the order -> "One moment." (always the same silent handoff)
  -> payment member silently asks Ringup: is payment needed for THIS purchase?
       required      -> "Let's knock out payment now..." (must complete before the call ends)
       optional      -> one offer, never blocks
       not_required  -> says nothing at all -> wrap-up closes as your agent normally would
  -> wrap-up (your agent): announces success, reads the confirmation number, closes politely

A merchant changing their payment rule (or connecting to Ringup later) changes call behavior immediately, with no agent edits and no redeploy.

Notes

• The Vapi dashboard cannot render squad-scoped wiring: the Tools list shows apiRequest tools without names, and the squad canvas may show "No handoff tools configured" on your member before go-live. check reads the API and is the source of truth.
• --demo-caller +1... pins the caller id for dashboard/web test calls (they have no real caller id). Omit for production; the real caller flows via {{customer.number}}.
• --escalation +1... provisions a human-transfer fallback tool (temporary flag; escalation is becoming a Ringup merchant setting).