abacatepay

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 QR コードを作成する（直接）

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 回まで）

データベーススキーマの概要

プランテーブル

• id：プラン識別子（例：「pro-monthly」）
• priceInCents：センターボでの価格（R$ 29,90 = 2990）
• interval：「monthly」 | 「yearly」 | 「lifetime」
• limits：機能制限を含む JSONB
• features：表示する機能の JSONB 配列

サブスクリプションテーブル

• userId：ユーザーごとにサブスクリプションは 1 件（ユニーク）
• planId：現在のプラン
• status：「active」 | 「cancelled」 | 「expired」
• currentPeriodStart/End：サブスクリプションの有効期間

決済テーブル

• abacateBillingId：AbacatePay の請求 ID
• status：「pending」 | 「paid」 | 「expired」
• paidAt：決済確認のタイムスタンプ

よくあるパターン

以下を参照してください：references/integration-patterns.md：

• サブスクリプション管理
• 冪等な Webhook 処理
• 機能の利用制限
• エラー処理

API リファレンス

エンドポイントの完全なドキュメントについては、references/api-reference.mdを参照してください。

テストチェックリスト

• 環境変数が設定されている
• SDK が正常に接続する
• チェックアウトで請求が作成され、URL が返される
• Webhook がイベントを受信する（AbacatePay ダッシュボードを使用）
• 決済ステータスが正しく更新される
• 決済後にサブスクリプションが作成される
• 冪等性により重複が防止される