Skip to main content
このプロンプトをAIコードエディタ(Cursor、Copilotなど)にコピーして、チェックアウト統合を作成:

構築するもの

チェックアウトセッションは動的に生成される支払いページです。静的な製品リンクを共有する代わりに、以下が可能です:
  • 顧客メールの事前入力
  • カスタムmetadataでの注文追跡
  • カスタム成功URLの設定
  • サブスクリプションのトライアル期間の有効化
  • 購入者層に合わせた言語と支払い方法の調整

前提条件

  • Waffo Pancakeアカウント
  • APIキー(Dashboard → API と開発)
  • 少なくとも1つの製品が作成済み

基本的なチェックアウトセッション

最もシンプルなチェックアウトセッションには製品IDと通貨が必要です。

TypeScript SDK を使用(推奨)

REST APIを直接使用

レスポンス:
顧客をcheckoutUrlにリダイレクトして支払いを完了します。

リダイレクトのベストプラクティス

チェックアウトページを開くためにwindow.open()を使用しないでください。 Safariや多くのモバイルブラウザは、非同期コールバック(例:API呼び出しの後)から開かれるポップアップウィンドウをブロックします。これにより、顧客のチェックアウトが警告なしに失敗します。
推奨アプローチ:
支払い後、顧客はあなたのsuccessUrlにリダイレクトされます。successUrlはそのまま使われ、プレースホルダーは置き換えられません。成功ページでこの購入を識別するには、セッション作成前に自社の識別子(社内注文番号など)をsuccessUrlのクエリパラメータに含め、支払いの確定は Webhook で確認してください。

顧客メールの事前入力

事前入力してメール入力ステップをスキップ:
ユースケース: ユーザーが既にアプリにログインしているため、メールがわかっている場合。

購入者層に合わせたチェックアウトの調整

ホスト型チェックアウトは既定でグローバル向けに構成されています。通貨がサポートする全ての支払い方法を表示し、購入者のブラウザ言語で開き、フォームは空欄です。世界中に販売するならこれが正しい既定値です。しかし購入者の大半が一つの市場から来るなら、絞り込むべきです。普段使っているウォレットだけが母語で表示され、メールも既に入力されていれば、購入者が迷って離脱することは大幅に減ります。 これを制御するのはチェックアウトセッションの 4 つのパラメータで、いずれも任意かつ互いに独立しています:

手順

  1. 購入者が実際に支払う通貨で価格を設定する。 どの支払い方法を提示できるかを決めるのは購入者の所在地ではなく通貨です。選ぶ前に対応表を確認してください。
  2. language を購入者のロケールに設定する。 購入者が複数市場に分散しているなら省略して構いません。ブラウザ言語の検出で十分対応できます。
  3. 支払い方法をその市場で使われているものに絞る。 単一市場なら includePaymentMethods で購入者が知っている方法だけを列挙します。複数市場なら excludePaymentMethods が適しています。通貨が元々提供しない値は無視されるため、一つのブラックリストを通貨横断で使えます。
  4. 購入者がログイン済みなら必ず buyerEmail を事前入力する。 購入者は既にあなたのサービスにアカウントを持っています。再度メールを尋ねると迷いを生みます(「登録時と同じにすべき?」)。認証済みチェックアウトでは buyerIdentity と buyerEmail を併せて渡してください。
  5. 税額の事前入力が不要なら billingDetail は渡さない。 渡すとチェックアウトがその国の支払い市場に固定され、購入者は切り替えられなくなります。

例

中国本土

購入者は WeChat Pay で支払い、簡体字中国語を読みます。WeChat Pay は CNY または USD 建ての単発商品で利用でき、1 注文あたり約 ¥1,000(≈ $140)が上限です。
サブスクリプションでは WeChat Pay を使えないため、サブスクリプション商品では includePaymentMethods を外し、購入者にカードで支払わせてください。

日本

購入者は JPY 建ての価格と日本語 UI を期待します。カードも各ウォレットも JPY に対応しているため絞り込みは不要です。通貨と言語を設定し、支払い方法は既定のままにします。

複数市場

リクエスト時に、既に持っている手掛かり(アカウントの国、UI ロケール、選択されたプラン)から購入者ごとに構成を選びます。推測できないものは省略し、チェックアウトの既定動作に任せてください。
支払い方法のフィルタには API Key 認証が必要です。 includePaymentMethods と excludePaymentMethods は Store Slug セッションおよび link モードのボタンでは黙って無視されます。どの支払い方法を提示するかは加盟店側の商業判断(手数料・精算)であり、サーバー側でのみ決められます。language と buyerEmail はどちらのモードでも有効です。
includePaymentMethods の各値は、送信した「商品タイプ × 通貨」でサポートされている必要があります。そうでない場合、リクエストは 400 Payment methods not supported で失敗します。また、単一の注文で支払い方法が非表示になることもあります(例:WeChat Pay が 1 注文あたりの上限を超えた場合)。一つの方法だけを開放する際は、価格がその上限内に収まるようにしてください。

metadataでの追跡

チェックアウトセッションを内部システムに関連付け:
Metadata はチェックアウトセッションに保存され、Webhook ペイロードの orderMetadata フィールドで返されます。マーチャントの認証情報(API Key)では checkoutSession を GraphQL で照会できません。

トライアル付きサブスクリプション

サブスクリプション製品のトライアル期間を有効化:
シート数量はまだAPI経由でサポートされていません。単発商品、新規サブスクリプション、プラン変更では、couponId でクーポンを適用するか、promotionCode でコードを事前入力するか、allowPromotionCodes: true でコード入力欄を表示できます —— 割引とプロモーションを参照してください。

請求先情報付きサブスクリプション

税金計算のために消費者の請求先情報を事前入力:

動的成功URL

成功ページにデータを渡す:
successUrlへはそのままリダイレクトされ、{SESSION_ID}などのプレースホルダーは置き換えられません。必要な識別子は自分で URL に含め、支払いの確定は Webhook で確認してください。

完全な例:SaaSアップグレードフロー

SDKを使用してユーザーのサブスクリプションをアップグレードする実際の例:
クライアントサイドでチェックアウトを処理する必要がある場合(例:SPA):

パラメータリファレンス


次のステップ

Webhookの処理

支払い完了時に通知を受ける

支払いの検証

Webhook署名を安全に検証