abacatepay

Assist with AbacatePay payment gateway integration for Brazilian SaaS applications.

Quick Reference

Installation

bun add abacatepay-nodejs-sdk

Environment Variables

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

import AbacatePay from "abacatepay-nodejs-sdk";
const abacate = AbacatePay(process.env.ABACATEPAY_API_KEY!);

Common Tasks

1. Create a PIX Payment

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)

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

const response = await abacate.pixQrCode.check({ id: "pix_abc123" });
// response.data.status: "PENDING" | "PAID" | "EXPIRED" | "CANCELLED"

4. Simulate Payment (Dev Mode)

await abacate.pixQrCode.simulatePayment({ id: "pix_abc123" });

Webhook Handling

Signature Verification (HMAC-SHA256)

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 | |-------|-------------| | billing.paid | Payment confirmed via PIX | | withdraw.done | Withdrawal completed | | withdraw.failed | Withdrawal failed |

Webhook Payload Structure

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

• 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