Back to Details

abacatepay

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

AbacatePay Integration Helper

AbacatePay集成助手

Assist with AbacatePay payment gateway integration for Brazilian SaaS applications.
协助为巴西SaaS应用集成AbacatePay支付网关。

Quick Reference

快速参考

Installation

安装

bash
bun add abacatepay-nodejs-sdk
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
bash
ABACATEPAY_API_KEY="abp_live_..."      # 从控制台获取的API密钥
ABACATEPAY_WEBHOOK_SECRET="whsec_..."  # Webhook密钥
NEXT_PUBLIC_APP_URL="https://..."      # 回调URL

SDK Initialization

SDK初始化

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

Common Tasks

常见任务

1. Create a PIX Payment

1. 创建PIX支付

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 }
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（单位：分）
  }],
  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)

2. 直接创建PIX二维码

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 }
typescript
const response = await abacate.pixQrCode.create({
  amount: 2990, // R$ 29,90
  expiresIn: 3600, // 1小时
  description: "Payment description",
});

// response.data: { id, brCode, brCodeBase64, status, expiresAt }

3. Check Payment Status

3. 检查支付状态

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

4. Simulate Payment (Dev Mode)

4. 模拟支付（开发模式）

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

Webhook Handling

Webhook处理

Signature Verification (HMAC-SHA256)

签名验证（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));
}
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

Webhook事件

EventDescription
billing.paid
Payment confirmed via PIX
withdraw.done
Withdrawal completed
withdraw.failed
Withdrawal failed
事件说明
billing.paid
通过PIX确认支付
withdraw.done
提现完成
withdraw.failed
提现失败

Webhook Payload Structure

Webhook负载结构

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;
    };
  };
}
typescript
interface WebhookPayload {
  id: string;              // 事件ID（用于幂等性）
  event: string;           // 事件类型
  devMode: boolean;        // 若为测试环境则为True
  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)
方式费用
PIX每笔交易固定R$ 0,80
信用卡3.5% + R$ 0,60
提现R$ 0,80（每月最多20笔）

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
  • id
    : 套餐标识（例如："pro-monthly"）
  • priceInCents
    : 价格（分）（R$ 29,90 = 2990）
  • interval
    : "monthly" | "yearly" | "lifetime"
  • limits
    : 包含功能限制的JSONB
  • features
    : 展示功能的JSONB数组

Subscriptions Table

订阅表

  • userId
    : One subscription per user (unique)
  • planId
    : Current plan
  • status
    : "active" | "cancelled" | "expired"
  • currentPeriodStart/End
    : Subscription validity
  • userId
    : 每个用户对应一个订阅（唯一）
  • planId
    : 当前套餐
  • status
    : "active" | "cancelled" | "expired"
  • currentPeriodStart/End
    : 订阅有效期

Payments Table

支付表

  • abacateBillingId
    : AbacatePay billing ID
  • status
    : "pending" | "paid" | "expired"
  • paidAt
    : Payment confirmation timestamp
  • abacateBillingId
    : AbacatePay账单ID
  • status
    : "pending" | "paid" | "expired"
  • paidAt
    : 支付确认时间戳

Common Patterns

常见模式

See references/integration-patterns.md for:
  • Subscription management
  • Idempotent webhook handling
  • Feature gating
  • Error handling
查看references/integration-patterns.md获取以下内容：
  • 订阅管理
  • 幂等Webhook处理
  • 功能权限控制
  • 错误处理

API Reference

API参考

See references/api-reference.md for complete endpoint documentation.
查看references/api-reference.md获取完整的端点文档。

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
  • 已配置环境变量
  • SDK连接成功
  • 结账流程可创建账单并返回URL
  • Webhook可接收事件（使用AbacatePay控制台）
  • 支付状态更新正确
  • 支付后创建订阅
  • 幂等性可防止重复操作