AgentSkillsCN

abacatepay

协助 Next.js 项目集成 AbacatePay 支付功能。当您需要实现 PIX 支付、管理订阅、处理 Webhook,或调试支付流程时,请使用此工具。它涵盖 SDK 使用、Webhook 验证,以及巴西 SaaS 应用的账单管理。

SKILL.md
--- frontmatter
name: abacatepay
description: "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."
allowed-tools: Read, Glob, Grep, Write, Edit, Bash

AbacatePay Integration Helper

Assist with AbacatePay payment gateway integration for Brazilian SaaS applications.

Quick Reference

Installation

bash
bun add abacatepay-nodejs-sdk

Environment Variables

bash
ABACATEPAY_API_KEY="abp_live_..."      # API key from dashboard
ABACATEPAY_WEBHOOK_SECRET="whsec_..."  # Webhook secret
NEXT_PUBLIC_APP_URL="https://..."      # For callback URLs

SDK 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

EventDescription
billing.paidPayment confirmed via PIX
withdraw.doneWithdrawal completed
withdraw.failedWithdrawal 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

MethodFee
PIXR$ 0,80 flat per transaction
Credit Card3.5% + R$ 0,60
WithdrawalR$ 0,80 (up to 20/month)

Database Schema Overview

Plans Table

  • id: Plan identifier (e.g., "pro-monthly")
  • priceInCents: Price in centavos (R$ 29,90 = 2990)
  • interval: "monthly" | "yearly" | "lifetime"
  • limits: JSONB with feature limits
  • features: JSONB array of display features

Subscriptions Table

  • userId: One subscription per user (unique)
  • planId: Current plan
  • status: "active" | "cancelled" | "expired"
  • currentPeriodStart/End: Subscription validity

Payments Table

  • abacateBillingId: AbacatePay billing ID
  • status: "pending" | "paid" | "expired"
  • paidAt: Payment confirmation timestamp

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