abacatepay
Original:🇺🇸 English
Translated
Help with AbacatePay payment integration in Next.js projects. Use when implementing PIX payments, managing subscriptions, handling webhooks, or debugging payment flows. Covers SDK usage, webhook verification, and billing management for Brazilian SaaS applications.
53installs
Sourceandrehfp/tinyplate
Added on
NPX Install
npx skill4agent add andrehfp/tinyplate abacatepayTags
Translated version includes tags in frontmatterSKILL.md Content
View Translation Comparison →AbacatePay Integration Helper
Assist with AbacatePay payment gateway integration for Brazilian SaaS applications.
Quick Reference
Installation
bash
bun add abacatepay-nodejs-sdkEnvironment Variables
bash
ABACATEPAY_API_KEY="abp_live_..." # API key from dashboard
ABACATEPAY_WEBHOOK_SECRET="whsec_..." # Webhook secret
NEXT_PUBLIC_APP_URL="https://..." # For callback URLsSDK Initialization
typescript
import AbacatePay from "abacatepay-nodejs-sdk";
const abacate = AbacatePay(process.env.ABACATEPAY_API_KEY!);Common Tasks
1. Create a PIX Payment
typescript
const response = await abacate.billing.create({
frequency: "ONE_TIME",
methods: ["PIX"],
products: [{
externalId: "plan-pro",
name: "Plano Pro",
quantity: 1,
price: 2990, // R$ 29,90 in centavos
}],
customer: {
email: "user@example.com",
name: "João Silva",
},
returnUrl: "https://app.com/pricing",
completionUrl: "https://app.com/billing/success",
});
// response.data: { id, url, status, amount }2. Create PIX QR Code (Direct)
typescript
const response = await abacate.pixQrCode.create({
amount: 2990, // R$ 29,90
expiresIn: 3600, // 1 hour
description: "Payment description",
});
// response.data: { id, brCode, brCodeBase64, status, expiresAt }3. Check Payment Status
typescript
const response = await abacate.pixQrCode.check({ id: "pix_abc123" });
// response.data.status: "PENDING" | "PAID" | "EXPIRED" | "CANCELLED"4. Simulate Payment (Dev Mode)
typescript
await abacate.pixQrCode.simulatePayment({ id: "pix_abc123" });Webhook Handling
Signature Verification (HMAC-SHA256)
typescript
import crypto from "crypto";
function validateSignature(payload: string, signature: string, secret: string): boolean {
const expected = crypto
.createHmac("sha256", secret)
.update(payload)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}Webhook Events
| Event | Description |
|---|---|
| Payment confirmed via PIX |
| Withdrawal completed |
| Withdrawal failed |
Webhook Payload Structure
typescript
interface WebhookPayload {
id: string; // Event ID (use for idempotency)
event: string; // Event type
devMode: boolean; // True if test environment
data: {
billing?: {
id: string;
amount: number;
status: string;
};
};
}Pricing
| Method | Fee |
|---|---|
| PIX | R$ 0,80 flat per transaction |
| Credit Card | 3.5% + R$ 0,60 |
| Withdrawal | R$ 0,80 (up to 20/month) |
Database Schema Overview
Plans Table
- : Plan identifier (e.g., "pro-monthly")
id - : Price in centavos (R$ 29,90 = 2990)
priceInCents - : "monthly" | "yearly" | "lifetime"
interval - : JSONB with feature limits
limits - : JSONB array of display features
features
Subscriptions Table
- : One subscription per user (unique)
userId - : Current plan
planId - : "active" | "cancelled" | "expired"
status - : Subscription validity
currentPeriodStart/End
Payments Table
- : AbacatePay billing ID
abacateBillingId - : "pending" | "paid" | "expired"
status - : Payment confirmation timestamp
paidAt
Common Patterns
See references/integration-patterns.md for:
- Subscription management
- Idempotent webhook handling
- Feature gating
- Error handling
API Reference
See references/api-reference.md for complete endpoint documentation.
Testing Checklist
- Environment variables configured
- SDK connects successfully
- Checkout creates billing and returns URL
- Webhook receives events (use AbacatePay dashboard)
- Payment status updates correctly
- Subscription created after payment
- Idempotency prevents duplicates