pagokit

The agent that picks and implements the right payment method for your app — from your terminal, with Claude Code.

tododeia.com · @soyenriquerocha · enrique@tododeia.com

🇪🇸 Leer en español · 📖 About · 🗺️ Coverage

---

Why it exists.

Every guide frames payment integration as a choice problem: thirty gateways, pick one. Choosing takes an afternoon. What takes weeks — and what silently fails in production — is everything after:

• A webhook that verifies a signature but never checks a timestamp, so a captured event is replayable forever.
• A webhook verified against the API key instead of the signing secret. It fails every event, and the developer goes off to debug the hashing algorithm.
• amount * 100 on a Japanese customer. JPY has no minor unit, so that is a 100× overcharge.
• A refund endpoint on a Pix integration, where refunding a charge is not an operation that exists.
• A payment_intent.succeeded handler that grants access, on a URL anyone can post to.

None of these throw. Most pass code review. PagoKit exists to make them hard to write.

It analyses your project, asks three questions, and generates a vertical-complete integration: frontend, checkout endpoint, authenticated webhook, database migration, customer portal, refund path, error mapper, production checklist and an audit trail.

Everything runs locally. No account, no API key, no telemetry. The only network calls are the ones your generated code makes to your own provider.

---

Three deterministic engines.

An LLM asked to write payment code produces something plausible. Plausible is exactly the failure mode that matters here. So the parts that must be correct aren't left to the model — they're ordinary programs, with tests.

	What it does	Why it isn't the model's job
Validators	Node checks on PreToolUse / PostToolUse hooks that block an insecure write	The model cannot argue with a non-zero exit code
Advisor	scripts/advise.js — a pure function from situation to ranked providers	Same input, same answer, every rejection carries its reason. "Why not X?" has an exact answer
Signer	scripts/sign-event.js — generates a validly signed event for any provider	Testing a handler means a valid event accepted, a forged one rejected, a replayed one rejected

---

What it knows.

42 providers · 136 payment methods · 74 countries (71 with a local provider) · 106 currencies with their ISO 4217 exponent · 6 webhook verification families in use.

What PagoKit writes for you

Provider	Level	Role	Buyer coverage	Subscriptions	MoR	Onboarding
Lemon Squeezy	full build	mor	Global	✓	✓	application_review
Mercado Pago	full build	psp	AR · BR · CL · CO · MX · PE · UY	✓	—	self_serve
Stripe	full build	psp	US · CA · UK · EU · MX · BR · SG · AU · …	✓	—	self_serve
Wompi	full build	acquirer	CO	—	—	application_review

What PagoKit knows and recommends, but doesn't write

Another 38 providers with verified catalog data: the advisor compares them, computes their fees and explains their constraints — and tells you plainly that the code is yours to write. They move up to build once their signature scheme is verified and transcribed.

• Wave 1 — Asaas · Bold.co · Conekta · Kushki · Paddle (Paddle Billing) · Polar
• Wave 2 — Culqi · Flow.cl · Pagar.me · Transbank Webpay Plus · dLocal Go
• Wave 3 — Fintoc · Mobbex · Placetopay (Evertec) · Recurrente · ePayco
• Wave 4 — Adyen · GoCardless · Mollie · Redsys (TPV Virtual) · Revolut Merchant (Revolut Business)
• Wave 5 — Airwallex · Antom (Ant International — Alipay+ / Alipay / WeChat Pay acquiring) · Midtrans (GoTo Financial) · PayMongo · Razorpay · Xendit
• Wave 6 — Flutterwave · Paymob · Paystack · Safaricom M-Pesa (Daraja API) · Tap Payments · Yoco
• Wave 7 — Authorize.Net (Visa Acceptance) · Hyperswitch (Juspay) · Lago · RevenueCat · Square

Payment methods, because outside card-mature markets the right question is which rail you need, not which gateway:

Category	Methods	Examples
Cards	8	Bancontact · Credit/Debit Card · mada · Meeza · OmanNet
Wallets	43	Airtel Money · Alipay · AlipayHK · Alipay+ · Apple Pay
Bank transfer	31	ACH Credit · Botón Bancolombia · Bancolombia Transfer · BenefitPay · Bre-B
QR / instant	11	Bizum · CoDi · DuitNow · NQR (NIBSS QR) · PayNow
Cash vouchers	14	Alfamart / Indomaret (cash over counter) · Baloto · Boleto Bancário · Efecty · Fawry
Direct debit	8	ACH Direct Debit · Bacs Direct Debit · BECS Direct Debit (Australia) · PAC (Chile direct debit) · PayTo
Mobile money	2	M-Pesa · MTN MoMo
BNPL	11	Afterpay / Clearpay · Akulaku PayLater · BillEase · Billie (B2B invoice / BNPL) · EMI / Cardless EMI (India)
Crypto	2	USDC Stablecoin · USDT Stablecoin
Open banking	1	Pay by Bank (open banking)
Card present	1	Card present (terminal)
Benefits (EBT/HSA)	2	SNAP EBT · HSA / FSA card
Store billing	2	Apple In-App Purchase · Google Play Billing

Full country × provider matrix: docs/COVERAGE.md.

---

What it will and won't build for you.

A wide catalog is only useful if it's honest about its own edges. Every provider carries an integration level, and the advisor states it every time:

Level	What happens
build	PagoKit writes the full idiomatic integration.
generic	PagoKit writes a working scaffold from the provider's verification family, and tells you it's a scaffold.
advise	PagoKit gives you the recommendation, the fee maths and a checklist — and says plainly that the code is yours to write.

Backing that up is one rule the build enforces:

If a provider's webhook scheme isn't verified against its own documentation (evidence.confidence != "high"), the generator must not emit a signature verifier. It emits re-fetch, event-id dedup, and a loud TODO instead.

A verifier built on an unverified scheme is worse than none: it looks correct and accepts forged events.

---

How it works.

Step	What happens
1. SCAN	Reads package.json, route files, DB schema. Detects stack, ORM, deploy target, language, and use cases like marketplace or mobile IAP.
2. ASK	Three questions, capped at five. Country and buyers · one-time or recurring · which local rails you need.
3. MATCH	Runs the ranking engine. Hard filters first — including can you even open an account there, and can you get keys in time. Sanctioned markets are refused, not ranked.
4. BUILD	The integration-specialist subagent writes the files, with the validators watching every write.

---

Installation.

git clone https://github.com/Hainrixz/agente-pagokit ~/agente-pagokit
cd ~/your-project
claude --plugin-dir ~/agente-pagokit

Then run /pagokit:start.

Requires Node.js ≥ 18 and Claude Code 2.x.

---

Deterministic security.

Security rules aren't advice in a markdown file the model may or may not follow. They're Node processes wired to Claude Code's hooks. A write that breaks one is denied.

Blocks	Because
A webhook handler with no signature verification	Anyone who knows the URL can mint a succeeded event
request.json() before verifying	The HMAC covers the exact bytes; parsing first breaks it permanently and silently
Math.random() or Date.now() as an idempotency key	Guessable keys collide across tenants and duplicate charges survive retries
A live key inline in source	Git history, screenshots, Sentry traces
.env written before .gitignore covers it	The single most common credential leak there is
amount * 100 on a zero-decimal currency	A 100× overcharge that nothing throws on
=== on a signature	A timing oracle — and on shared-secret schemes it is the whole security control
Card data crossing your own server	Moves you from PCI SAQ A to SAQ D, a six-figure project
A refund call on an irreversible rail	On Pix or SPEI, "refund the charge" isn't an operation
A webhook route that would overwrite an existing one	Clobbering someone's Clerk or Inngest endpoint

When the tool is wrong and you're right:

// pagokit-ignore: webhook-has-signature -- custom verifier in lib/auth/payments.ts

Every bypass is logged to .pagokit/audit.log, so it's a decision on the record rather than a silent hole.

Full rule set with enforcement tiers: SECURITY_RULES.md.

---

Commands.

Command	What it does
/pagokit:start	The wizard: analyse, ask, recommend, implement.
/pagokit:test	Sends a valid, a forged and a replayed event to your local handler. Works for every provider whose scheme is signable — not just the one with a CLI.
/pagokit:doctor	Read-only audit of an existing integration: credentials, key modes, signature verification, routed events, schema, replay protection.

---

What gets generated.

For a Next.js App Router + Prisma project:

app/api/checkout/route.ts        Server-side price lookup · UUID idempotency · correct minor units
app/api/webhook/<provider>/      Raw body · signature · replay window · event-id dedup · fast ack
app/api/portal/route.ts          Customer self-service (subscriptions)
app/api/refund/route.ts          Authorisation-checked — or the payout path on irreversible rails
components/CheckoutButton.tsx    Hosted, embedded or widget, per the provider
lib/payments/<provider>.ts       SDK init · API version pinned
lib/payments/errors.ts           Cross-provider error taxonomy · ES/EN
prisma/schema.prisma             payments · subscriptions · customers · idempotency_keys
                                 · webhook_events_processed
payment-page-scripts.json        PCI DSS 4.0.1 §6.4.3 authorised-script inventory
.env.example                     Test-mode values only
PAGOKIT_INTEGRATION.md           Audit trail · events routed · what's still TODO
PAGOKIT_PRODUCTION_CHECKLIST.md  Steps to go live
PAGOKIT_TAX_TODO.md              Only where the market mandates e-invoicing