Waffo 決済設定:Next.js チェックアウト手順
Waffo には二つの形態があり、設定も異なります。Uncorne の連携は同じチェックアウトと Webhook 契約で両方をサポートするため、このチュートリアルでは両方を扱います。最後には、ライセンスを発行するサンドボックス購入が完成します。
ステップ 0:どの Waffo を接続するか知る
Waffo は単一の製品ではありません。Pancake はグローバルな Merchant of Record チェックアウトです——Waffo Pancake ドキュメント参照。Acquiring は東南アジアのアクワイアリングゲートウェイで、Webhook は RSA 署名です——Waffo Acquiring ドキュメント参照。Merchant of Record は販売税と VAT を代行します。この概念は Merchant of Record の概要で説明されています。地域のアクワイアリング契約がなければ Pancake を選んでください。

ステップ 1:形態と環境を設定する
WAFFO_FLAVOR に pancake または acquiring を設定します。既定は pancake で、アダプターがそれに応じて端点と署名を切り替えます。すべての開発手順で WAFFO_ENVIRONMENT=test を設定してください。テスト環境のまま本番化するのが、初回決済を失う最も一般的な方法です——チェックアウトは正常に見えますが、実際の資金は動かずライセンスも発行されません。
ステップ 2:認証情報を集める
Pancake には WAFFO_STORE_SLUG(または WAFFO_STORE_ID / WAFFO_MERCHANT_ID)と WAFFO_PRIVATE_KEY が必要です。Acquiring には商户契約フィールド——WAFFO_ACQUIRING_MERCHANT_INFO、WAFFO_ACQUIRING_USER_INFO、WAFFO_ACQUIRING_PAYMENT_INFO、WAFFO_ACQUIRING_ORDER_CURRENCY、WAFFO_ACQUIRING_ORDER_DESCRIPTION——に加え、環境ごとの Webhook 公開鍵が必要です。これらは .env.local に置き、リポジトリには絶対に入れないでください。
PAYMENT_PROVIDER=waffo
WAFFO_FLAVOR=pancake
WAFFO_ENVIRONMENT=test
WAFFO_STORE_SLUG=your-store
WAFFO_PRIVATE_KEY=sk_test_xxx
WAFFO_PRICE_ID_BUYOUT=price_buyout_test
WAFFO_PRICE_ID_CARE=price_care_test
ステップ 3:製品と価格を作成する
Waffo ダッシュボードで Buyout に一度限り製品、Care に定期製品を作成し、その価格 id を WAFFO_PRICE_ID_BUYOUT と WAFFO_PRICE_ID_CARE にコピーします。ブラックフライデー促销なら別の価格 id を作り、WAFFO_PRICE_ID_BUYOUT_BF と WAFFO_PRICE_ID_CARE_BF を設定します。Webhook のプラン推定が BF id を自動認識するため、促销にコード変更は不要です。

ステップ 4:Webhook を設定する
Waffo を /api/payments/webhook/waffo 端点に向けます。Pancake はプラットフォームの RSA 公開鍵(WAFFO_WEBHOOK_PUBLIC_KEY、test と prod のバリエーションあり)で検証します。Acquiring は RSA でリクエストに署名し、同じ公開鍵が必要です。ペイロードを信頼する前に、必ずサーバー側で署名を検証してください——決してスキップしないでください。未検証イベントを受け付ける Webhook 端点なら、誰でも curl 一発で支払い済み注文を偽装できます。
ハンドラーは三つのことをします。署名を検証し、価格 id からプランを推定し、冪等にライセンス付与を呼び出して、再試行イベントが二つのライセンスを発行しないようにします。イベント id と価格 id をログに残してください。支払い後にアクセスが付与されないとき、最初に見る場所がそのログです。
export async function POST(req: Request) {
const raw = await req.text();
if (!verifyWaffoSignature(raw, req.headers)) {
return new Response("bad signature", { status: 400 });
}
const event = JSON.parse(raw);
const plan = inferPlanFromPriceId(event.price_id);
await grantLicence(event.customer, plan, event.id);
return new Response("ok");
}
上記の Next.js App Router route handler はサーバーで動作します。署名検証が属するのはまさにそこであり、クライアントコンポーネントではありません。
ステップ 5:プロバイダーを設定する
PAYMENT_PROVIDER=waffo と上記の変数を設定します。チェックアウト呼び出しは現在のプランに合った価格 id を解決し、Webhook は価格 id からプランを推定してライセンスを付与します。価格 id が未設定なら、チェックアウトは表示モードにフォールバックします——プレビューには便利ですが、売上には無用です。
ステップ 6:サンドボックスでテストする
テスト環境とテスト購入を使います。Webhook が発火し、プランが正しく推定され、ライセンスキーが発行されることを確認します。次に失敗パスをテストします。未検証の署名は 400 で拒否されなければなりません。実際のサンドボックス往復がグリーンになるまで本番化しないでください。

よくある三つの失敗のトラブルシューティング
チェックアウトは開くのにライセンスが出ない場合、価格 id がほぼ間違いありません。Webhook ログと照合してください。テストで署名検証が失敗する場合は、テスト用ではなく本番用の公開鍵を使っています。プランが常に Buyout になるなら、Care の価格 id が環境にコピーされていません。
後でゲートウェイを切り替える
Uncorne では五つのプロバイダーアダプターがこの契約を共有するため、Creem、Stripe、PayPal、Lemon Squeezy も同じコードパスで動き、環境変数だけが変わります。同じ手順は Creem 決済設定チュートリアルを参照し、コミット前に選ぶならゲートウェイ比較を読んでください。
チェックアウト呼び出しが実際にすること
訪問者が Buyout または Care をクリックすると、サーバーアクションが現在のプランを読み、対応する価格 id を解決して Waffo ホスト型チェックアウトセッションを開きます。価格 id はサーバーから来るため、顧客が URL パラメータを書き換えて Buyout の価格で Care を買うことはできません。セッションには内部ユーザー id への参照が metadata として載り、決済が確定した後、Webhook はその参照でどのアカウントに付与すべきかを知ります。
Pancake と Acquiring、実際に変わること
二つの形態はチェックアウトと Webhook 契約を共有しますが、署名の経路が異なります。Pancake はプラットフォームの RSA 公開鍵でペイロードを検証し、Acquiring は各リクエストに RSA 署名し、あなた側でも同じ公開鍵を期待します。したがって検証ヘルパーは、アルゴリズム分岐をハードコードするのではなく、形態を引数に取るべきです。テスト用と本番用で公開鍵を分け、すべての Webhook ログ行に環境を刻んでください。環境ラベルのないログは、障害時にはほとんど役に立ちません。
記録すべき Webhook イベント
Waffo は決済完了、返金、ディスピュートのイベントを送ります。すべてを三つのフィールドで記録してください。イベント id、価格 id、顧客参照です。価格 id がログにあるおかげで、数か月後にも「この人は結局どのプランを買ったのか?」と推測せずに答えられます。ディスピュートイベントは、黙って取り消すのではなくレビュー対象としてライセンスにフラグを立ててください。支払い済み顧客を切る前に、人が証拠を読む余地が必要です。
冪等性はオプションではない
端点の応答が遅いと、Waffo は Webhook を再試行します。ハンドラーがイベントを確認する前にライセンスを発行すると、遅いデータベース呼び出し一つで同じ購入に二つのライセンスが付与されることがあります。イベント id をユニーク列に保存し、重複を成功の空操作として扱ってください。「なぜこの顧客に二つの席があるのか?」というチケットの最大の原因で、順調な経路のテストでは見えません。
サンドボックスは一つの順調な経路ではなくマトリクスで
一度の成功購入はデモであってテストではありません。本番前に、テストモードでこの短いマトリクスを走らせてください:
- 標準価格 id で Buyout——ライセンス発行、プラン推定が正しい。
- 標準価格 id で Care——定期プランが有効、更新日が記録される。
- プロモーションフラグを付けて BF 価格 id——BF プランが推定され、コード変更不要。
- 同じイベント id の Webhook を再送——二つ目のライセンスも二重請求もない。
- 署名を改ざんしたリクエスト——400 で拒否され、ログに残る。
5 行目は公開鍵の設定ミスを捕まえます。署名検証が壊れたまま順調な経路だけがグリーンなら、それはセキュリティホールを本番に出したのと同じです。
本番化チェックリスト
WAFFO_ENVIRONMENT を production に切り替え、本番の秘密鍵と本番の Webhook 公開鍵に差し替え、Webhook URL を本番ドメインの HTTPS に向けます。そして少額の実際の購入を一つ行い、支払い・Webhook・プラン推定・ライセンスというチェーン全体を眺めてください。テスト価格 id を本番に持ち込まないでください。「ステージングでは動いた」チケットの最も一般的な原因です。
次に読むもの
五つのアダプター契約により、これらの運用習慣はそのまま引き継げます。ゲートウェイ比較は Merchant of Record がその手数料に見合う時を説明し、課金ゲートウェイガイドはより広い判断を扱います。
FAQ
どの Waffo 形態を使うべきですか?+
グローバルな Merchant of Record チェックアウトには pancake を使います。特定のフィールドと RSA 署名を必要とする地域のアクワイアリング契約がある場合のみ acquiring を使ってください。
Waffo Webhook の署名を検証する必要がありますか?+
はい。連携は両形態ともプラットフォーム公開鍵でサーバー側検証します。検証を省くと、署名なしリクエストで誰でも支払い済みイベントを偽装できます。
ライセンスはどう発行されますか?+
Webhook が価格 id(BF id 含む)からプランを推定し、冪等にライセンス付与を呼び出します。価格 id 未設定ならチェックアウトは表示モードにフォールバックします。
支払い後にアクセスが付与されない場合、何を確認すべきですか?+
Webhook ログの価格 id と環境変数を照合してください。価格 id の誤り、テストでの本番公開鍵の使用、Care 価格 id の欠落が最も一般的な三つの原因です。