✨ AIでインストール
✨ AIでインストール
このプロンプトをAIコードエディタ(Cursor、Copilotなど)にコピーして、チェックアウト統合を作成:
構築するもの
チェックアウトセッションは動的に生成される支払いページです。静的な製品リンクを共有する代わりに、以下が可能です:- 顧客メールの事前入力
- カスタムmetadataでの注文追跡
- カスタム成功URLの設定
- サブスクリプションのトライアル期間の有効化
- 購入者層に合わせた言語と支払い方法の調整
前提条件
- Waffo Pancakeアカウント
- APIキー(Dashboard → API と開発)
- 少なくとも1つの製品が作成済み
基本的なチェックアウトセッション
最もシンプルなチェックアウトセッションには製品IDと通貨が必要です。TypeScript SDK を使用(推奨)
REST APIを直接使用
checkoutUrlにリダイレクトして支払いを完了します。
リダイレクトのベストプラクティス
推奨アプローチ:successUrlにリダイレクトされます。successUrlはそのまま使われ、プレースホルダーは置き換えられません。成功ページでこの購入を識別するには、セッション作成前に自社の識別子(社内注文番号など)をsuccessUrlのクエリパラメータに含め、支払いの確定は Webhook で確認してください。
顧客メールの事前入力
事前入力してメール入力ステップをスキップ:購入者層に合わせたチェックアウトの調整
ホスト型チェックアウトは既定でグローバル向けに構成されています。通貨がサポートする全ての支払い方法を表示し、購入者のブラウザ言語で開き、フォームは空欄です。世界中に販売するならこれが正しい既定値です。しかし購入者の大半が一つの市場から来るなら、絞り込むべきです。普段使っているウォレットだけが母語で表示され、メールも既に入力されていれば、購入者が迷って離脱することは大幅に減ります。 これを制御するのはチェックアウトセッションの 4 つのパラメータで、いずれも任意かつ互いに独立しています:手順
- 購入者が実際に支払う通貨で価格を設定する。 どの支払い方法を提示できるかを決めるのは購入者の所在地ではなく通貨です。選ぶ前に対応表を確認してください。
languageを購入者のロケールに設定する。 購入者が複数市場に分散しているなら省略して構いません。ブラウザ言語の検出で十分対応できます。- 支払い方法をその市場で使われているものに絞る。 単一市場なら
includePaymentMethodsで購入者が知っている方法だけを列挙します。複数市場ならexcludePaymentMethodsが適しています。通貨が元々提供しない値は無視されるため、一つのブラックリストを通貨横断で使えます。 - 購入者がログイン済みなら必ず
buyerEmailを事前入力する。 購入者は既にあなたのサービスにアカウントを持っています。再度メールを尋ねると迷いを生みます(「登録時と同じにすべき?」)。認証済みチェックアウトではbuyerIdentityとbuyerEmailを併せて渡してください。 - 税額の事前入力が不要なら
billingDetailは渡さない。 渡すとチェックアウトがその国の支払い市場に固定され、購入者は切り替えられなくなります。
例
中国本土
購入者は WeChat Pay で支払い、簡体字中国語を読みます。WeChat Pay は CNY または USD 建ての単発商品で利用でき、1 注文あたり約 ¥1,000(≈ $140)が上限です。includePaymentMethods を外し、購入者にカードで支払わせてください。
日本
購入者は JPY 建ての価格と日本語 UI を期待します。カードも各ウォレットも JPY に対応しているため絞り込みは不要です。通貨と言語を設定し、支払い方法は既定のままにします。複数市場
リクエスト時に、既に持っている手掛かり(アカウントの国、UI ロケール、選択されたプラン)から購入者ごとに構成を選びます。推測できないものは省略し、チェックアウトの既定動作に任せてください。includePaymentMethods の各値は、送信した「商品タイプ × 通貨」でサポートされている必要があります。そうでない場合、リクエストは 400 Payment methods not supported で失敗します。また、単一の注文で支払い方法が非表示になることもあります(例:WeChat Pay が 1 注文あたりの上限を超えた場合)。一つの方法だけを開放する際は、価格がその上限内に収まるようにしてください。metadataでの追跡
チェックアウトセッションを内部システムに関連付け:orderMetadata フィールドで返されます。マーチャントの認証情報(API Key)では checkoutSession を GraphQL で照会できません。
トライアル付きサブスクリプション
サブスクリプション製品のトライアル期間を有効化:シート数量はまだAPI経由でサポートされていません。単発商品、新規サブスクリプション、プラン変更では、
couponId でクーポンを適用するか、promotionCode でコードを事前入力するか、allowPromotionCodes: true でコード入力欄を表示できます —— 割引とプロモーションを参照してください。請求先情報付きサブスクリプション
税金計算のために消費者の請求先情報を事前入力:動的成功URL
成功ページにデータを渡す:successUrlへはそのままリダイレクトされ、{SESSION_ID}などのプレースホルダーは置き換えられません。必要な識別子は自分で URL に含め、支払いの確定は Webhook で確認してください。
完全な例:SaaSアップグレードフロー
SDKを使用してユーザーのサブスクリプションをアップグレードする実際の例:パラメータリファレンス
次のステップ
Webhookの処理
支払い完了時に通知を受ける
支払いの検証
Webhook署名を安全に検証