mcpField
A
abacatepay

abacatepay

github.com/andrehfp开发7450 次安装40 周前更新
代码仓库

关于 abacatepay

面向巴西 SaaS 开发者的 AbacatePay 集成 Skill，涵盖 PIX 支付、Webhook 验签及订阅处理模式，并使用 Node.js SDK。

主要功能

  1. 01创建 PIX 账单和二维码
  2. 02查询及模拟支付状态
  3. 03验证 Webhook 签名
  4. 04处理订阅与支付模式

适用场景

  1. 01为 SaaS 应用添加 PIX 结账
  2. 02处理支付确认 Webhook
  3. 03在开发环境测试支付流程

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/andrehfp/tinyplate --skill abacatepay

安装后在 Claude Code 中输入/abacatepay确认已加载。

附带文件references/api-reference.mdreferences/integration-patterns.md

详细介绍

AbacatePay 集成助手

协助巴西 SaaS 应用集成 AbacatePay 支付网关。

快速参考

安装
bun add abacatepay-nodejs-sdk
环境变量
ABACATEPAY_API_KEY="abp_live_..."      # API key from dashboard
ABACATEPAY_WEBHOOK_SECRET="whsec_..."  # Webhook secret
NEXT_PUBLIC_APP_URL="https://..."      # For callback URLs
SDK 初始化
import AbacatePay from "abacatepay-nodejs-sdk";
const abacate = AbacatePay(process.env.ABACATEPAY_API_KEY!);

常见任务

1. 创建 PIX 支付
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: "[email protected]",
    name: "João Silva",
  },
  returnUrl: "https://app.com/pricing",
  completionUrl: "https://app.com/billing/success",
});

// response.data: { id, url, status, amount }
2. 创建 PIX 二维码（直接创建）
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. 检查支付状态
const response = await abacate.pixQrCode.check({ id: "pix_abc123" });
// response.data.status: "PENDING" | "PAID" | "EXPIRED" | "CANCELLED"
4. 模拟支付（开发模式）
await abacate.pixQrCode.simulatePayment({ id: "pix_abc123" });

Webhook 处理

签名验证（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 事件
事件描述
billing.paid已通过 PIX 确认支付
withdraw.done提现已完成
withdraw.failed提现失败
Webhook 负载结构
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;
    };
  };
}

定价

方式费用
PIX每笔交易固定收取 R$ 0,80
信用卡3.5% + R$ 0,60
提现R$ 0,80（每月最多 20 笔）

数据库架构概览

Plans 表
  • id：套餐标识符（例如，“pro-monthly”）
  • priceInCents：以分为单位的价格（R$ 29,90 = 2990）
  • interval：“monthly” | “yearly” | “lifetime”
  • limits：包含功能限制的 JSONB
  • features：用于显示的功能 JSONB 数组
Subscriptions 表
  • userId：每位用户仅有一个订阅（唯一）
  • planId：当前套餐
  • status：“active” | “cancelled” | “expired”
  • currentPeriodStart/End：订阅有效期
Payments 表
  • abacateBillingId：AbacatePay 账单 ID
  • status：“pending” | “paid” | “expired”
  • paidAt：支付确认时间戳

常见模式

请参阅 references/integration-patterns.md，了解：

  • 订阅管理
  • 幂等的 Webhook 处理
  • 功能访问控制
  • 错误处理

API 参考

请参阅 references/api-reference.md，了解完整的端点文档。

测试清单

  • 已配置环境变量
  • SDK 已成功连接
  • 结账已创建账单并返回 URL
  • Webhook 已收到事件（使用 AbacatePay 控制面板）
  • 支付状态已正确更新
  • 支付完成后已创建订阅
  • 幂等性可防止重复操作

评论

支持 Markdown