skill-abacatepay-integration
Workflow
- Inspect the project backend boundary first: Netlify/Vercel function, Express route, server action, Edge Function, or other server-only layer.
- Keep all AbacatePay calls behind that backend boundary. Browser code calls the project API, never AbacatePay directly with secrets.
- Validate customer data before billing creation: email, cellphone with country code, CPF/CNPJ without punctuation, amount in cents, plan ID, and tenant/user identity.
- Create billing with stable metadata:
user_id, tenant_id, plan_id, internal correlation ID, and payment link token when present.
- Persist provider IDs, normalized status, amount, currency, raw event reference, and support/debug timestamps.
- Process webhooks idempotently, update entitlements from trusted backend evidence, and audit every access transition.
- Verify with local webhook tooling or provider test events plus project build/typecheck.
Current API Shape (v2)
Use API v2 for new work. API v1 remains only for legacy integrations:
- base URL:
https://api.abacatepay.com/v2
- hosted checkout:
POST /checkouts/create
- subscriptions:
POST /subscriptions/create
- transparent PIX/card/boleto checkout:
POST /transparents/create
- webhook management:
POST /webhooks/create
- auth header:
Authorization: Bearer <abacatepay-api-key>
- current checkout events:
checkout.completed, checkout.refunded, checkout.disputed
- current subscription events:
subscription.completed, subscription.renewed, subscription.cancelled
The old v1 routes such as /v1/billing/create and events such as billing.paid are legacy-compatible references. Do not copy them into new integrations; if maintaining v1, isolate an adapter and plan migration to v2.
Guardrails
- Keep
ABACATEPAY_API_KEY and webhook secrets server-side.
- Treat checkout redirect as advisory. Grant access only after trusted backend/webhook confirmation.
- Deduplicate webhook processing by the v2 event ID and the provider checkout/subscription ID.
- Do not log API keys, webhook secrets, full CPF/CNPJ, full phone numbers, or unnecessary PII.
- Keep plan and entitlement rules in local product tables, not encoded only in AbacatePay objects.
- Support retries and out-of-order delivery by re-reading local payment state before mutation.
Local Pattern
The example-saas project has a useful boundary pattern: frontend client calls a Netlify function, the function uses the server API key and service-role Supabase client, and the webhook updates users/plans after billing.paid.
Read {{USER_HOME}}/Documents/Code/example-saas/src/lib/abacatepay.ts only when implementing a similar client boundary or validating local conventions.
Validation
- Confirm no
ABACATEPAY_API_KEY or webhook secret appears in browser bundles or VITE_ variables.
- Simulate or replay
billing.paid and confirm idempotent entitlement update.
- Check invalid CPF/CNPJ, invalid cellphone, duplicate webhook, expired billing, and failed provider response paths.
- Run the project build/typecheck/lint when available.
- Confirm the integration uses the v2 payload shape (
apiVersion: 2) and does not assume the legacy billing.* event names.
Official References
Related Skills
skill-saas-factory
skill-saas-core-limits
skill-supabase-rls
skill-security-hooks
1---2name: skill-abacatepay-integration3description: Integrate AbacatePay PIX/card billing, customers, QRCode PIX, billing webhooks, CPF/CNPJ validation, BRL SaaS checkout, payment receipts, refunds, cancellations, and entitlement sync for Brazilian SaaS products.4category: payments5risk: medium6source: official-docs-plus-local-saas-patterns7last_verified: 2026-08-068metadata:9 source: https://skillmd.com/skills/iapro-community/skill-abacatepay-integration10---1112# skill-abacatepay-integration1314## Workflow15161. Inspect the project backend boundary first: Netlify/Vercel function, Express route, server action, Edge Function, or other server-only layer.172. Keep all AbacatePay calls behind that backend boundary. Browser code calls the project API, never AbacatePay directly with secrets.183. Validate customer data before billing creation: email, cellphone with country code, CPF/CNPJ without punctuation, amount in cents, plan ID, and tenant/user identity.194. Create billing with stable metadata: `user_id`, `tenant_id`, `plan_id`, internal correlation ID, and payment link token when present.205. Persist provider IDs, normalized status, amount, currency, raw event reference, and support/debug timestamps.216. Process webhooks idempotently, update entitlements from trusted backend evidence, and audit every access transition.227. Verify with local webhook tooling or provider test events plus project build/typecheck.2324## Current API Shape (v2)2526Use API v2 for new work. API v1 remains only for legacy integrations:27- base URL: `https://api.abacatepay.com/v2`28- hosted checkout: `POST /checkouts/create`29- subscriptions: `POST /subscriptions/create`30- transparent PIX/card/boleto checkout: `POST /transparents/create`31- webhook management: `POST /webhooks/create`32- auth header: `Authorization: Bearer <abacatepay-api-key>`33- current checkout events: `checkout.completed`, `checkout.refunded`, `checkout.disputed`34- current subscription events: `subscription.completed`, `subscription.renewed`, `subscription.cancelled`3536The old v1 routes such as `/v1/billing/create` and events such as `billing.paid` are legacy-compatible references. Do not copy them into new integrations; if maintaining v1, isolate an adapter and plan migration to v2.3738## Guardrails39401. Keep `ABACATEPAY_API_KEY` and webhook secrets server-side.412. Treat checkout redirect as advisory. Grant access only after trusted backend/webhook confirmation.423. Deduplicate webhook processing by the v2 event ID and the provider checkout/subscription ID.434. Do not log API keys, webhook secrets, full CPF/CNPJ, full phone numbers, or unnecessary PII.445. Keep plan and entitlement rules in local product tables, not encoded only in AbacatePay objects.456. Support retries and out-of-order delivery by re-reading local payment state before mutation.4647## Local Pattern4849The example-saas project has a useful boundary pattern: frontend client calls a Netlify function, the function uses the server API key and service-role Supabase client, and the webhook updates users/plans after `billing.paid`.5051Read `{{USER_HOME}}/Documents/Code/example-saas/src/lib/abacatepay.ts` only when implementing a similar client boundary or validating local conventions.5253## Validation5455- Confirm no `ABACATEPAY_API_KEY` or webhook secret appears in browser bundles or `VITE_` variables.56- Simulate or replay `billing.paid` and confirm idempotent entitlement update.57- Check invalid CPF/CNPJ, invalid cellphone, duplicate webhook, expired billing, and failed provider response paths.58- Run the project build/typecheck/lint when available.59- Confirm the integration uses the v2 payload shape (`apiVersion: 2`) and does not assume the legacy `billing.*` event names.6061## Official References6263- https://docs.abacatepay.com/pages/reference/introduction64- https://docs.abacatepay.com/pages/payment/create65- https://docs.abacatepay.com/pages/webhooks66- https://docs.abacatepay.com/pages/changelog6768## Related Skills6970- `skill-saas-factory`71- `skill-saas-core-limits`72- `skill-supabase-rls`73- `skill-security-hooks`