概要
Waffo Pancake API を使用すると、決済インフラストラクチャ全体をプログラムで管理できます。- ストアの作成と管理
- 商品の作成（単発購入およびサブスクリプション）
- チェックアウトセッションの生成と注文の処理
- サブスクリプションと請求の管理
- GraphQL によるデータクエリ
- 返金の処理
ベース URL
すべての API リクエストは以下の URL に対して行います。アーキテクチャ
API はハイブリッドアプローチを採用しています。- REST エンドポイント (
/v1/actions/...) — すべての書き込み操作（作成、更新、削除） - GraphQL (
/v1/graphql) — すべての読み取り操作（クエリ）
POST メソッドのみを使用します。GET、PUT、PATCH、DELETE メソッドはありません。
TypeScript SDK
公式@waffo/pancake-ts SDK は、完全な型安全性で API 全体をラップします。認証、リクエスト署名、冪等キー、Webhook 検証を自動的に処理します。
認証
Waffo Pancake は、すべてのプログラム的な API アクセスに API Key 認証 を使用します。API Key 認証は SDK によって自動的に処理されます。 公開チェックアウトフローでは、X-Store-Slug ヘッダーを使用した Store Slug 認証を使用します。
認証について詳しく ->
共通ヘッダー
API Key 認証ヘッダー（
X-Merchant-Id、X-Timestamp、X-Signature）は SDK によって自動的に処理されます。クライアント初期化時に Merchant ID と秘密鍵を提供するだけで済みます。リクエストフォーマット
- メソッド: すべての書き込みエンドポイントは
POSTを使用 - ボディ: JSON
- タイムスタンプ: ISO 8601 UTC（例：
2026-01-23T00:00:00.000Z） - 金額: 表示フォーマット文字列（例：
"29.00"= $29.00 USD） - 通貨: ISO 4217 コード（例：
USD、EUR、JPY） - ステータス値: 常に小文字（例：
active、ACTIVEではない）
ID フォーマット
外部向けのすべてのエンティティ ID は Short ID フォーマットを使用します:{PREFIX}_{base62}。
Checkout Session ID は特別なフォーマットを使用します:
cs_ + UUID（例：cs_550e8400-e29b-41d4-a716-446655440000）。Short ID システムの一部ではありません。レスポンスフォーマット
成功
エラー
errors 配列では、errors[0] が障害の根本原因です。後続のエントリはリクエストチェーン内の上位レベルの呼び出し元を表します。エラーの layer フィールド
各エラーには、システムのどの部分がエラーを生成したかを示す layer 文字列が含まれます。デバッグ時に根本原因を特定するために使用してください。値は常に定義済みのレイヤー名のいずれかです（例："gateway"、"store"、"product"）。
HTTP ステータスコード
環境
API Key 認証は、署名の検証に成功した鍵に基づいて環境を自動的に決定します。Store Slug 認証ではX-Environment ヘッダーが必要です。
冪等性
X-Idempotency-Key ヘッダーを含めることで、書き込み操作の重複を防止できます。
可能な場合はキーを SDK に生成させてください。SDK は
merchantId + パス + ボディ から決定的なハッシュを導出するため、構造上リクエストごとに一意になります。自分で構築する場合は、merchantId と UUID を組み合わせてください。
エンドポイントグループ
認証
チェックアウトフロー用のセッショントークン発行
ストア
ストアの作成、更新、削除
単発購入商品
単発購入商品の作成と管理
サブスクリプション商品
階層型サブスクリプション商品とグループの作成
注文
チェックアウトセッションと注文の作成
サブスクリプション
サブスクリプションライフサイクルの管理
返金
返金のリクエストと処理
GraphQL
GraphQL ですべてのデータをクエリ