チェックアウトセッションの作成

商品バージョン、価格、通貨を固定するチェックアウトセッションを作成します。これは単発商品とサブスクリプション商品の両方のチェックアウトフローの最初のステップです。一般的なフローは以下の通りです。

マーチャントがチェックアウトセッションを作成（サーバーサイド）
フロントエンドに checkoutUrl を返す
customer がリンクをクリックしてホスティングされたチェックアウトページに移動
customer が請求情報を入力し、税額をプレビューし、注文を完了

POST /v1/actions/checkout/create-session

認証： API Key または Store Slug

リクエストボディ（API Key）

フィールド	型	必須	説明
`productId`	string	Yes	商品 ID（Short ID フォーマット `PROD_xxx`）
`currency`	string	Yes	ISO 4217 通貨コード（例：`USD`、`EUR`、`JPY`）
`priceSnapshot`	object	No	セッション作成時に価格を上書き（API Key のみ、以下参照）
`withTrial`	boolean	No	トライアル期間を有効にする（サブスクリプション商品のみ）
`buyerEmail`	string	No	チェックアウトページで customer のメールを事前入力
`billingDetail`	object	No	請求情報を事前入力（以下参照）
`successUrl`	string	No	決済成功後のリダイレクト URL を上書き
`expiresInSeconds`	number	No	セッション TTL（秒単位、デフォルト：`2700` = 45 分、API Key のみ）
`darkMode`	boolean	No	チェックアウトページのダークモードを有効にする
`metadata`	object	No	セッションに添付するカスタムキー値ペア
`orderMerchantExternalId`	string	No	マーチャント業務側の注文識別子（最大 128 文字）
`language`	string	No	チェックアウトの言語（IETF BCP 47）。サポートされる列挙値のいずれかである必要があります：en, pt-BR, es-MX, id-ID, vi-VN, ru-RU, en-KE, es-PE, es-CO, es-CL, zh-Hant-TW, zh-Hant-HK, th-TH, ja-JP, en-NG, ko-KR, en-HK, zh-Hans-HK, pl-PL, tr-TR, zh-Hans, ms-MY。チェックアウトページのデフォルト言語を設定します。customer はページ上で切り替えられます。
`includePaymentMethods` / `excludePaymentMethods`	string[]	No	排他——いずれか一方のみ指定します。include はホワイトリスト：これらのみ提供（`card`、`applepay`、`googlepay`、`wechat`）、各値は「商品タイプ × 通貨」の組み合わせでサポートされている必要があります。exclude はブラックリスト：その通貨がサポートする全手段からこれらを除外し、その通貨が元々提供していない値は無視されるため通貨横断で再利用できます。両方省略した場合、その通貨がサポートする全手段を提供します。

リクエストボディ（Store Slug）

フィールド	型	必須	説明
`productId`	string	Yes	商品 ID（Short ID フォーマット `PROD_xxx`）
`currency`	string	Yes	ISO 4217 通貨コード
`buyerEmail`	string	No	customer のメールを事前入力
`billingDetail`	object	No	請求情報を事前入力（以下参照）
`successUrl`	string	No	決済成功後のリダイレクト URL を上書き
`darkMode`	boolean	No	チェックアウトページのダークモードを有効にする
`language`	string	No	チェックアウトの言語（IETF BCP 47）。サポートされる列挙値のいずれかである必要があります：en, pt-BR, es-MX, id-ID, vi-VN, ru-RU, en-KE, es-PE, es-CO, es-CL, zh-Hant-TW, zh-Hant-HK, th-TH, ja-JP, en-NG, ko-KR, en-HK, zh-Hans-HK, pl-PL, tr-TR, zh-Hans, ms-MY。チェックアウトページのデフォルト言語を設定します。customer はページ上で切り替えられます。

Store Slug 認証では、クライアントサイドからの価格改ざんやセッション操作を防止するため、priceSnapshot、expiresInSeconds、metadata、orderMerchantExternalId、withTrial、includePaymentMethods、excludePaymentMethods はサポートされません（黙って無視されます）。決済手段は加盟店側の商業判断（チャネル手数料・精算サイクル）であり、ブラウザからの絞り込み・拡大は認められません——Store Slug で作成された session は常にその通貨がサポートする全手段を提供します。

ID 命名規約：同じフラット双キー名（checkout 側の orderMerchantExternalId、返金チケット側の refundTicketMerchantExternalId）が、リクエストボディ、webhook ペイロード、そしてその値を保持する全ての GraphQL 型を通じて使用されます — checkout 作成時に書き込んだ値は Order、Payment、Refund、webhook ペイロードのいずれからも同じフィールド名で読み戻せます。

Price Snapshot オブジェクト

フィールド	型	必須	説明
`amount`	string	Yes	表示フォーマット文字列としての価格（例：`"29.00"` = $29.00）
`taxIncluded`	boolean	No	金額に税が含まれているかどうか（デフォルト：`false`）
`taxCategory`	string	Yes	税計算用のカテゴリ（例：`saas`、`digital_goods`）

Billing Detail オブジェクト

フィールド	型	必須	説明
`country`	string	Yes	ISO 3166-1 alpha-2 国コード（例：`US`、`JP`、`DE`）
`isBusiness`	boolean	Yes	法人購入かどうか
`postcode`	string	No	郵便番号
`state`	string	No	州・県コード（例：`CA`、`NY`、`ON`）。どの請求先国でこのフィールドが必要になるかは、`preview-tax` エンドポイントが返す `rules.requiredFields` で示されます
`businessName`	string	No	法人の正式名称。`isBusiness: true` と併せて指定すると請求書に表示されます
`taxId`	string	No	税務登録番号（EU の VAT 番号など）。どの請求先国でこのフィールドが必要になるかは、`preview-tax` エンドポイントが返す `rules.requiredFields` で示されます

billingDetail を渡すと、キャッシャーは注文の請求先国と連動します：その国が属する市場の支払方法のみを提供し、買い手は市場を切り替えられません。適用されるのは注文最終の請求先国であり、送信した値ではありません。当社がカバーする支払市場に含まれない請求先国では、制限はかかりません。有効にする前にストアで許可している支払方法と照らし合わせてください — 連動先の市場がそのいずれも提供しない場合、その注文は決済できません。billingDetail を省略すればキャッシャーは制限されません。これが既定です。

セッションロック

チェックアウトセッション作成時に以下の値がロックされ、セッションの有効期間中は変更できません。 productVersionId、productName、priceInfo、storeName、billingPeriod、withTrial、theme、buyerEmail、billingDetail メールアドレスの正規化：すべてのメールフィールド（email / buyerEmail / contactEmail）はサーバー側で trim().toLowerCase() により正規化されてから保存・キャッシュ・下流呼び出しに使用されます。Foo@Bar.COM と foo@bar.com は同一アカウントとして扱われます。

リクエスト例

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

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

const session = await client.checkout.createSession({
  storeId: "STO_2D5F8G3H1K4M6N9P",
  productId: "PROD_7J3K5L8M2N4P6Q9R",
  productType: CheckoutSessionProductType.Onetime,
  currency: "USD",
  buyerEmail: "customer@example.com",
  language: "en",
  successUrl: "https://example.com/thank-you",
});

console.log(session.sessionId);   // "cs_550e8400-e29b-41d4-a716-446655440000"
console.log(session.checkoutUrl); // "https://checkout.waffo.ai/..."
console.log(session.expiresAt);   // "2026-01-22T10:30:00.000Z"

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Content-Type: application/json" \
  -H "X-Merchant-Id: MER_2D5F8G3H1K4M6N9P" \
  -H "X-Timestamp: 1711800000" \
  -H "X-Signature: BASE64_RSA_SIGNATURE" \
  -d '{
    "storeId": "STO_2D5F8G3H1K4M6N9P",
    "productId": "PROD_7J3K5L8M2N4P6Q9R",
    "productType": "onetime",
    "currency": "USD",
    "buyerEmail": "customer@example.com",
    "language": "en",
    "successUrl": "https://example.com/thank-you"
  }'

curl -X POST https://api.waffo.ai/v1/actions/checkout/create-session \
  -H "Content-Type: application/json" \
  -H "X-Store-Slug: my-store-abc123" \
  -H "X-Environment: test" \
  -d '{
    "productId": "PROD_7J3K5L8M2N4P6Q9R",
    "productType": "onetime",
    "currency": "USD"
  }'

import requests

response = requests.post(
    "https://api.waffo.ai/v1/actions/checkout/create-session",
    headers={
        "Content-Type": "application/json",
        "X-Merchant-Id": "MER_2D5F8G3H1K4M6N9P",
        "X-Timestamp": "1711800000",
        "X-Signature": "BASE64_RSA_SIGNATURE",
    },
    json={
        "storeId": "STO_2D5F8G3H1K4M6N9P",
        "productId": "PROD_7J3K5L8M2N4P6Q9R",
        "productType": "onetime",
        "currency": "USD",
        "buyerEmail": "customer@example.com",
        "language": "en",
    },
)

data = response.json()["data"]
print(data["checkoutUrl"])

成功レスポンス (200)

{
  "data": {
    "sessionId": "cs_550e8400-e29b-41d4-a716-446655440000",
    "checkoutUrl": "https://checkout.waffo.ai/my-store-abc123/checkout/cs_550e8400-e29b-41d4-a716-446655440000",
    "expiresAt": "2026-01-22T10:30:00.000Z"
  }
}

レスポンスフィールド

フィールド	型	説明
`sessionId`	string	Checkout Session ID（`cs_` + UUID フォーマット、Short ID ではない）
`checkoutUrl`	string	customer をホスティングされたチェックアウトページにリダイレクトするための完全な URL
`expiresAt`	string	セッションが期限切れになる ISO 8601 タイムスタンプ

エラー

リトライポリシー：4xx は一切リトライしない — リクエストを修正してから再送信。5xx は指数バックオフでリトライ（5s 開始、最大 3 回）。

ステータス	`errors[0].message`	意味	推奨処理
400	`Missing or invalid header: x-context-environment`	environment ヘッダーが欠落、または `test` / `prod` 以外	ヘッダーを修正して再送信
400	`Invalid JSON body`	リクエストボディが有効な JSON ではない	ボディを修正して再送信
400	`Missing required fields: productId, currency`	`productId` または `currency` が欠落	ボディを修正して再送信
400	`Invalid currency format: "X". Must be 3 uppercase letters (e.g., "USD", "EUR", "JPY")`	通貨コードが 3 文字の大文字ではない（ISO 4217）	有効な ISO 4217 コードを使用して再送信
400	`Invalid language, must be one of: en, pt-BR, … ms-MY`	`language` がサポートされる列挙値のいずれでもない	サポートされる `language` を使用するか省略してください
400	`includePaymentMethods and excludePaymentMethods are mutually exclusive`	両方のリストを同時に指定	どちらか一方のみ指定してください
400	`Invalid includePaymentMethods, must be one of: card, applepay, googlepay, wechat`	列挙外の値が含まれる	サポートされる値を使用するか省略してください
400	`Currency X is not supported for onetime payments`	通貨が決済手段マトリクス外（一回払い：USD・EUR・GBP・HKD・JPY・CNY、サブスクリプション：USD・EUR・GBP・HKD・JPY）	サポートされる通貨を使用してください
400	`Payment methods not supported for X (onetime): wechat`	`includePaymentMethods` が「商品タイプ × 通貨」で提供されない手段を要求	未サポートの手段を外してください
400	`No payment method remains for X (onetime) after applying excludePaymentMethods`	ブラックリストで全手段が除外された	除外する手段を減らしてください
400	`Expected format: PROD_xxx, got "..."`	`productId` Short ID のデコード失敗	`productId` のフォーマットを修正して再送信
400	`orderMerchantExternalId must not be empty`	指定後 trim で空になる	フィールドを省略するか、空でない値を指定
400	`orderMerchantExternalId must be at most 128 characters`	値が 128 文字を超過	128 文字以内に短縮
400	`Currency X is not supported for this product`	商品が要求された通貨の price snapshot を持たない	商品がサポートする通貨を使用
401	`Unauthorized`	API Key 署名が無効、または Store Slug が認識されない	認証ヘッダーを確認
403	`Store is not active`	ストアステータスが `active` でない	先にストアを有効化
403	`Store is not accepting payments`	`prod` 環境で、プラットフォームがこのストアの入金受付（`payin_enable`）を有効にしていない	プラットフォーム側のスイッチ — Waffo サポートへお問い合わせください
403	`Store is not approved for production payments`	`prod` 環境で、ストアが本番承認（`prod_enabled`、すなわち KYB 審査）を通過していない	`test` 環境を使用するか、KYB 審査を完了
403	`Product does not belong to this store`	商品が訪問中のストアに属していない	商品/ストアの組み合わせを確認
404	`Store not found`	スラッグに一致するストアがない	スラッグと environment を確認
404	`Product not found`	商品が存在しない	`productId` を確認
404	`Product not found or not active for this environment`	該当 environment で商品の active バージョンがない	この environment 用に商品バージョンを有効化
500	`Internal server error`	サーバ側の予期しない障害	指数バックオフでリトライ（5s 開始、最大 3 回）

payin_enable と prod_enabled は互いに独立した 2 つの条件です：payin_enable はプラットフォーム側が制御する入金受付スイッチ、prod_enabled は本番承認（KYB）のゲートです。prod 環境では、いずれか一方が満たされないだけで 403 になります。どちらも test 環境には適用されません。

デフォルトのセッション TTL は 45 分（2700 秒）です。API Key 認証を使用する場合、expiresInSeconds でカスタマイズできます。セッションは作成時に商品バージョンと価格をロックするため、価格変更は既存のセッションに影響しません。

概要

認証

マーチャント API（API Key）

Customer Portal API（Session Token）

GraphQL

チェックアウトセッションの作成

リクエストボディ（API Key）

リクエストボディ（Store Slug）

Price Snapshot オブジェクト

Billing Detail オブジェクト

セッションロック

リクエスト例

成功レスポンス (200)

レスポンスフィールド

エラー

​リクエストボディ（API Key）

​リクエストボディ（Store Slug）

​Price Snapshot オブジェクト

​Billing Detail オブジェクト

​セッションロック

​リクエスト例

​成功レスポンス (200)

​レスポンスフィールド

​エラー

リクエストボディ（API Key）

リクエストボディ（Store Slug）

Price Snapshot オブジェクト

Billing Detail オブジェクト

セッションロック

リクエスト例

成功レスポンス (200)

レスポンスフィールド

エラー