インテグレーション

まず接続パスを選ぶ

AI Integration

最速で導入既存コードベースがあり、Claude Code などのコーディングエージェントで設計、実装、検証まで進めたいチーム向けです。

API / SDK

最も高い制御性チェックアウトフローのカスタマイズ、サーバー側オーケストレーション、動的価格設定、細かな制御が必要なケース向けです。

Hosted Checkout

最もシンプルまず決済リンクで素早く収益化を確認し、その後で段階的に統合を深めたいチーム向けです。

どう選ぶか

いま重視したいこと	おすすめのパス	理由
まず最初の利用可能版を早く出したい	AI Integration	既存コードベースをもとに、コーディングエージェントで短時間に統合を進めやすい
決済フローやサーバー側ロジックを細かく制御したい	API / SDK	カスタムチェックアウト、動的価格、権限制御、内部オーケストレーションに向く
深い実装の前に収益化フローを検証したい	Hosted Checkout	エンジニアリングコストを抑えて素早く公開できる

多くのチームは、最初に Hosted Checkout や AI Integration で立ち上げ、その後に API / SDK へ拡張していきます。

典型的なインテグレーション構成

Waffo Pancake の統合は、通常次の 4 つで構成されます。

認証: サーバー側リクエストのための Merchant ID と API Key
商品とチェックアウト: 単発商品またはサブスクリプション商品を作成し、購入導線を用意
Webhook: 決済、返金、サブスクリプションイベントの受信
環境移行: テスト環境で検証し、その後本番へ公開

あなたのアプリケーション
    |
    +-- 認証 --> API / SDK リクエスト
    |
    +-- 商品 + チェックアウト --> 決済
    |
    +-- Webhook --> 注文・サブスクリプション同期

初日からすべてを実装する必要はありません。Hosted Checkout や AI Integration から始めて、後で API 利用を深めることもできます。

各パスで得られるもの

AI Integration

AI コーディングアシスタントに llms-full.txt と公式 skill コンテキストを読ませる
技術スタックに合わせた統合コード、Webhook 処理、検証手順を生成できる
既存コードベースがあり、実装時間を短縮したい場合に向く

API / SDK

商品、チェックアウト、Webhook、状態同期をサーバー側で完全に制御できる
動的価格、細かな権限管理、独自のバックエンド編成に向く
長期的なカスタマイズや複雑な課金ロジックに最適

Hosted Checkout

ダッシュボードで生成したチェックアウトリンクや公開購入導線をそのまま使える
深い開発投資の前に商用フローを検証したい場合に向く
多くの場合、最初の導入段階に最適

推奨の導入順序

アカウント作成

Merchant Dashboard でサインアップし、最初のストアを作成します。

認証を準備

マーチャントダッシュボードで Merchant ID と API Key を用意します。

商品を作成

商品タイプ、価格、課金周期を定義し、ダッシュボードまたは API で商品を作成します。

チェックアウトを実装

API で Checkout Session を作成するか、ダッシュボードで生成したチェックアウトリンクを使います。

Webhook を処理

決済、返金、サブスクリプションイベント用の Webhook エンドポイントを設定します。

エンドツーエンドで検証

テストモードとテストカードで全体フローを確認します。

本番公開

商品を公開し、本番環境へ切り替えます。

実装前に決めておくこと

コードを書く前に、次の点を明確にしておくと進めやすくなります。

単発商品、サブスクリプション、または両方を扱うか
超過利用、クレジット、見積もり金額などで動的価格が必要か
支払い完了後に付与するアクセス権限やリソースは何か
どの Webhook イベントで業務状態を更新するか
どの機能を本番移行までテスト環境に留めるか

これらがまだ曖昧なら AI Integration から始めるのが効率的です。すでに整理できているなら API / SDK パスの方が適しています。

主要な導線

認証

Merchant ID、API Key、サーバー側認証を設定します。

テストモード

実課金なしでフルフローを検証します。

Webhooks

リアルタイムイベントを受け取り、注文とサブスクリプションを同期します。

SDKs

公式 SDK、フレームワークパターン、コード例を確認します。

AI Integration

AI コーディングアシスタントで設計、実装、検証を進めます。

Quickstart

最初の決済フローからエンドツーエンドの導線を素早く理解します。

開発者設定

API と開発ページは、Waffo Pancake をアプリケーションと統合するためのツールを提供します。

APIキー

概要

APIキーは Waffo Pancake API へのサーバー間リクエストを認証します。

テストキー

test 環境用に作成
開発に使用
実際の課金なし
本番データと分離

本番キー

prod 環境用に作成
本番に使用
実際の支払いを処理
秘密鍵を安全に保管

キータイプ

キータイプ	ユースケース	説明
APIキー	サーバーサイドのみ	署名リクエスト、フルAPIアクセス

APIキー認証

API Key 認証は SDK が自動的に処理します。@waffo/pancake-ts をインストールし、Merchant ID と秘密鍵を提供するだけで、SDK がリクエストの署名を自動的に行います。

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

クライアントサイドコード、バージョン管理、パブリックリポジトリで秘密鍵を公開しないでください。

APIキーの作成

開発者に移動

ダッシュボード → API と開発 → APIキー

「APIキーを作成」をクリック

APIキージェネレーターが開きます。

キーペアを生成

「生成」をクリックしてキーペアを作成。

公開鍵がサーバーに送信されます
秘密鍵はあなたが保管します

キーに名前を付ける

説明的な名前を付ける（例：「本番サーバー」）

環境を選択

テストまたは本番環境を選択。

秘密鍵をダウンロード

重要： 秘密鍵をダウンロードして安全に保存。

秘密鍵は一度だけ表示されます。安全に保存してください — API認証に必要です。

キーの管理

アクション	説明
表示	キー名、作成日、環境を確認
削除	キーを永久に削除

Webhooks

Webhooksとは？

Webhooksは、Waffo Pancakeでイベントが発生したときにサーバーに通知します。

利用可能なイベント

イベント	トリガー
`order.completed`	注文完了
`subscription.activated`	サブスクリプション有効化
`subscription.payment_succeeded`	サブスクリプション決済成功
`subscription.updated`	サブスクリプション更新
`subscription.canceling`	サブスクリプションのキャンセル予定
`subscription.canceled`	サブスクリプション終了
`subscription.uncanceled`	サブスクリプションのキャンセル取り消し
`subscription.past_due`	サブスクリプション決済期限超過
`refund.succeeded`	返金処理成功
`refund.failed`	返金処理失敗

Webhooksのセットアップ

エンドポイントを追加

WebhookのURL（HTTPSが必須）を入力。

イベントを選択

受信したいイベントを選択。

設定を保存

Webhookエンドポイントを保存。

Webhookペイロード例

{
  "event": "order.completed",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "orderId": "660e8400-e29b-41d4-a716-446655440001",
    "amount": 2900,
    "currency": "USD",
    "status": "completed",
    "createdAt": "2026-01-15T10:30:00.000Z"
  }
}

すべてのIDはUUID v4形式です。金額は最小通貨単位です。タイムスタンプはISO 8601 UTC形式です。

Webhookベストプラクティス

素早くレスポンス

30秒以内に2xxステータスを返す。重い処理は非同期で行う。

重複を処理

イベントは複数回送信される可能性があります。イベントIDで重複排除。

リトライロジック

失敗したWebhooksは最大5回、遅延を増やしながらリトライされます（5分、30分、2時間、24時間）。

失敗を監視

ダッシュボードでWebhook配信ログを確認。

APIドキュメント

ベースURL

https://api.waffo.ai/v1

アーキテクチャ

Waffo Pancake はハイブリッド API を使用します：

REST（POST） — /v1/actions/... 経由のすべての書き込み操作
GraphQL — /v1/graphql 経由のすべての読み取り操作

認証例

SDK を使用した API キー認証（サーバー間通信）：

import { WaffoPancake } from "@waffo/pancake-ts";

const client = new WaffoPancake({
  merchantId: process.env.WAFFO_MERCHANT_ID!,
  privateKey: process.env.WAFFO_PRIVATE_KEY!,
});

const { store } = await client.stores.create({ name: "My Store" });

一般的なエンドポイント

エンドポイント	メソッド	説明
`/v1/actions/onetime-product/create-product`	POST	単発プロダクトを作成
`/v1/actions/subscription-product/create-product`	POST	サブスクリプションプロダクトを作成
`/v1/actions/onetime-order/create-order`	POST	チェックアウトセッションを作成
`/v1/actions/subscription-order/create-order`	POST	サブスクリプションチェックアウトを作成
`/v1/graphql`	POST	データをクエリ (GraphQL)

完全なAPIリファレンス

リクエスト/レスポンス例を含む完全なエンドポイントドキュメント。

セキュリティベストプラクティス

環境変数

秘密鍵はコードではなく環境変数に保存。

キーローテーション

特にチーム変更後は定期的にキーをローテーション。

キー分離

テストと本番で異なるAPIキーを使用。

安全な保管

プラットフォームのシークレット管理を使用して秘密鍵を保管。

テスト

テストモード

開発にはテストモードを使用：

すべてのエンドポイントが同じように動作
実際の課金は処理されない
テストカード番号が利用可能
フルWebhookテスト

テストカード

カード番号	動作
`4576 7500 0000 0110`	成功（Visa）
`2226 9000 0000 0110`	成功（Mastercard）
`4576 7500 0000 0220`	拒否

ログとデバッグ

Webhookログ

Webhook配信を追跡：

イベントタイプ
配信ステータス（成功/失敗）
エンドポイントからのHTTPレスポンス
リトライ回数とタイムスタンプ

​まず接続パスを選ぶ

AI Integration

API / SDK

Hosted Checkout

​どう選ぶか

​典型的なインテグレーション構成

​各パスで得られるもの

​AI Integration

​API / SDK

​Hosted Checkout

​推奨の導入順序

​実装前に決めておくこと

​主要な導線

認証

テストモード

Webhooks

SDKs

AI Integration

Quickstart

​開発者設定

​APIキー

​概要

テストキー

本番キー

​キータイプ

​APIキー認証

​APIキーの作成

​キーの管理

​Webhooks

​Webhooksとは？

​利用可能なイベント

​Webhooksのセットアップ

​Webhookペイロード例

​Webhookベストプラクティス

​APIドキュメント

​ベースURL

​アーキテクチャ

​認証例

​一般的なエンドポイント

完全なAPIリファレンス

​セキュリティベストプラクティス

環境変数

キーローテーション

キー分離

安全な保管

​テスト

​テストモード

​テストカード

​ログとデバッグ

​Webhookログ

まず接続パスを選ぶ

どう選ぶか

典型的なインテグレーション構成

各パスで得られるもの

AI Integration

API / SDK

Hosted Checkout

推奨の導入順序

実装前に決めておくこと

主要な導線

開発者設定

APIキー

概要

キータイプ

APIキー認証

APIキーの作成

キーの管理

Webhooks

Webhooksとは？

利用可能なイベント

Webhooksのセットアップ

Webhookペイロード例

Webhookベストプラクティス

APIドキュメント

ベースURL

アーキテクチャ

認証例

一般的なエンドポイント

セキュリティベストプラクティス

テスト

テストモード

テストカード

ログとデバッグ

Webhookログ