Quick Start
API Reference
Preview Endpoint
Session Validity: Checkout sessions expire after 24 hours by default, or 15 minutes when
confirm: true.Prerequisites
You need:- An active Dodo Payments merchant account
- API credentials from Developer → API Keys in the dashboard
- At least one product created in Products
Creating Your First Checkout Session
- Node.js SDK
- Python SDK
- REST API
API Response
All methods return:session_id is guaranteed to be present. When payment_method_id is provided, the charge processes immediately and checkout_url is null. Use the returned payment_id instead.
When confirm: true, the payment is created at session-creation time, and the response also includes payment_id, client_secret, and publishable_key for use with the Dodo Payments checkout SDK.
Redirect Your Customer
1
Extract the checkout URL
Get
checkout_url from the API response.2
Redirect to checkout
Send your customer to the URL:Alternatively, open in a new window:
3
Handle the return
After payment, customers are redirected to your
return_url with query parameters:Example redirect:
セッションステータスの確認
セッションのステータスを確認するには、Get Checkout Session (GET /checkouts/{id}) を呼び出します。レスポンスには、セッションの id、created_at、customer_email、customer_nameに加えて、payment_idとpayment_statusが含まれます。顧客が詳細を入力中の場合、両方の支払いフィールドはnullです。顧客が支払いを送信すると、payment_statusに、succeeded、failed、processingなどの支払いステータスが格納されます。フルフィルメントの信頼できる情報源としてwebhookを使用してください。
リクエストボディ
必須フィールド
array
必須
チェックアウトセッションに含める商品の配列です。各商品には、ダッシュボードの有効な
product_idが必要です。同じセッションで、単発決済商品1つとサブスクリプション商品1つを組み合わせることができます。カートにはサブスクリプション商品を2つ以上入れることもできますが、その場合は単発商品を入れることができません。Multi-Subscription Cartを参照してください。カートに入れられる商品は最大20個です。オプションフィールド
Customer Information
Customer Information
Payment Configuration
Payment Configuration
array
チェックアウト中に顧客が利用できる決済手段を制御します。特定の市場やビジネス要件に合わせた最適化に役立ちます。一般的なオプション:
credit、debit、upi_collect、apple_pay、google_pay、amazon_pay、klarna、affirm、afterpay_clearpay、cashapp、ach、multibanco、bancontact_card、eps、ideal、blik、gcash、ali_pay_hk、fps、touch_n_go、paypal完全な一覧については、Create Checkout Session API referenceを参照してください。例:string
デフォルトの通貨選択を固定の請求通貨で上書きします。ISO 4217通貨コードを使用します。対応通貨:
USD、EUR、GBP、CAD、AUD、INRなど例: 米ドルの場合は"USD"、ユーロの場合は"EUR"このフィールドはAdaptive Currencyが有効な場合のみ有効です。Adaptive Currencyが無効な場合、APIはこのフィールドを破棄し、通貨は商品の価格または請求先の国から取得します。boolean
デフォルト:"false"
再訪顧客に以前保存した決済手段を表示し、チェックアウトの速度とユーザー体験を向上させます。
Session Management
Session Management
string
支払い完了後に顧客をリダイレクトするURLです。リダイレクト時、Dodo PaymentsはURLにクエリパラメータを追加します(上記のリダイレクトテーブルを参照)。リダイレクトURLの例:
license_keyとemailのクエリパラメータを使用すると、追加のAPI呼び出しなしで、戻り先ページにライセンスキーを表示したり、確認をすぐに送信したりできます。string
顧客が戻るボタンをクリックした場合、またはチェックアウトセッションをキャンセルした場合にリダイレクトするURLです。指定しない場合、戻るボタンは表示されません。
cancel_urlを設定すると、購入を完了せずに顧客がサイトへ戻れる明確な方法を提供できます。boolean
デフォルト:"false"
trueの場合、すべてのセッション詳細を直ちに確定します。必須データが不足している場合、APIはエラーをスローします。
confirm: trueの場合:- すべての請求先住所フィールドが必須になります(
minimal_addressがtrueの場合は、countryとzipcodeのみ) payment_method_idを指定すると、請求を直ちに処理できます- セッションの有効期限が24時間ではなく15分になります
payment_method_idを指定する場合、既存のcustomer_idが必要です
array
1つ以上の積み重ねた割引コードをチェックアウトセッションに適用します。コードは配列の順序で適用されます(最初のコードが開始価格を引き下げ、2番目のコードが割引後の価格をさらに引き下げます)。1セッションあたり最大20個のコードを指定できます。Purchasing Power Parityが有効な場合、開始価格は基本価格ではなくPPP調整後の金額です。以下の単数形の
discount_codeフィールドは非推奨ですが、引き続き完全にサポートされています。同じリクエストでdiscount_codesと組み合わせることはできません。string
非推奨
非推奨 — 新しい統合では
discount_codesを使用してください。後方互換性のため引き続き機能しますが、同じリクエストでdiscount_codesと組み合わせることはできません。object
セッションに関する追加情報を保存するカスタムのキーと値のペアです。
boolean
このセッションに対するmerchantのデフォルト3DS動作を上書きします。
boolean
デフォルト:"false"
最小限の住所収集モードを有効にします。有効にすると、チェックアウトでは以下のみを収集します:
- 国: 税額決定のため常に必須
- ZIP/郵便番号: 売上税、VAT、GSTの計算に必要な地域でのみ必須
confirm: trueでは、zipcode(およびcountry)のみが必須で、その他の請求先住所フィールドは任意のままです。string
紐付けられた顧客に属する保存済みの支払い方法。
confirm: trueと既存のcustomer.customer_idが必要です。支払い方法は、決済の通貨に対する利用可否が検証されます。設定すると請求が直ちに処理され、checkout_urlがnullとして返されます。代わりに、返されたpayment_idを使用してください。boolean
デフォルト:"false"
完全なセッションURLではなく、短縮されたチェックアウトURLを返す場合はtrueです。
string
コレクションベースのチェックアウトフローで使用するProduct collection ID。設定する場合は、空の
product_cart配列を渡してください。セッション作成時に割引コードを事前適用することはできません。Product Collectionsを参照してください。string
顧客のTax ID(VAT番号など)。
billing_addressとcountryが必要です。string
Tax IDに関連付けられた任意の法人名または法的名称(最大250文字)。有効な
tax_idとともに指定すると、顧客の個人名の代わりに請求書へ表示されます。integer
インドのカードに対するINR e-mandate用の、Merchantレベルのmandate floor(INRパイサ単位)を上書きします。プロセッサに送信されるmandate金額は
max(this_floor, actual_billing_amount)であるため、請求額がこれを下回る場合、実質的に顧客向けの認証上限額となります。未設定の場合はMerchant設定が適用され、それも未設定の場合はシステムのデフォルト値₹15,000が適用されます。UI Customization
UI Customization
object
チェックアウトインターフェースの外観と動作をカスタマイズします。
Feature Flags
Feature Flags
object
チェックアウトセッションの特定の機能と動作を設定します。
Custom Fields
Custom Fields
array
カスタムフォームフィールドを使用して、チェックアウト中に顧客から追加情報を収集します。チェックアウトセッションごとに最大5つのカスタムフィールドを定義できます。顧客の回答はwebhook payloadに含まれ、APIから利用できます。
- Webhooks:
payment.succeeded、subscription.active、およびその他の関連イベントのpayloadにcustom_field_responses配列が含まれます - APIレスポンス: Paymentおよびsubscriptionオブジェクトに
custom_field_responsesが含まれます
Subscription Configuration
Subscription Configuration
object
サブスクリプション商品を含むチェックアウトセッションの追加設定。
使用例
単一商品のシンプルなチェックアウト
複数商品のカート
複数サブスクリプションのカート
1回のチェックアウトで複数のサブスクリプション商品を販売するには、product_cartにサブスクリプション商品を2つ以上追加します。顧客は1回だけ支払い、Dodo Paymentsは商品ごとに1つの支払い、1つの請求書、1つのサブスクリプションを作成します。各サブスクリプションには独自の請求サイクルがあり、それぞれ個別に更新されるため、月額商品と年額商品を同じカートに入れられます。
- 単発商品を入れることはできません。APIは
422でリクエストを拒否します。 - サブスクリプション商品は最大20個まで入れられます。
- 同じ商品を2回登録することはできません。商品の数量を2つ以上販売するには、代わりに
quantityを設定してください。 - オンデマンド請求(
subscription_data.on_demand)は使用できません。 - カートに適用した割引コードは1回の利用としてカウントされます。
subscription_data.trial_period_daysはカート内のすべてのサブスクリプションに適用されます。これを指定しない場合、各サブスクリプションではそれぞれの商品に設定されたトライアルが使用されます。設定せず、Prevent Trial Misuseが有効な場合、顧客がすでにトライアルを利用した商品はトライアルなしで開始されます。
生成された支払いにはis_multi_subscription: trueがあり、開始するすべてのサブスクリプションがsubscription_idsに一覧表示されます。単一のサブスクリプションが支払いを所有していないため、そのsubscription_idはnullです。payment.succeeded webhookにも同じフィールドが含まれます。支払いの種類を確認するにはis_multi_subscriptionを読み取り、subscription_idsの長さでは判断しないでください。
支払いが成功すると、カートに対して1つのpayment.succeededイベントが、各サブスクリプションに対して1つのsubscription.activeイベントが届きます。その後、各サブスクリプションは独自に更新、プラン変更、キャンセルされ、更新ごとに独自の請求書が作成されます。
1つのカートから作成されたすべてのサブスクリプションは、顧客がチェックアウトで使用した支払い方法を共有します。そのうち1つの支払い方法を更新すると、Dodo Paymentsは、同じ決済通貨と請求通貨を持ち、active、on_hold、past_due、またはpausedである、同じカートのすべてのサブスクリプションへ新しい支払い方法を移します。商品の価格通貨が異なる場合でも、カート内のすべてのサブスクリプションは同じ決済通貨と請求通貨で開始されます。プラン変更などの後続の変更により、サブスクリプションが別の決済通貨または請求通貨へ移ることがあります。そのサブスクリプションでは以前の支払い方法が保持されるため、個別に更新してください。on_holdサブスクリプションの場合、更新によって再試行されるのは、そのサブスクリプションの未払い請求書のみです。
トライアル期間付きサブスクリプション
事前確定済みチェックアウト
通貨を上書きするチェックアウト
リピーター向けの保存済み支払い方法
Tax IDを収集するB2Bチェックアウト
割引コードを積み重ねたダークテーマのチェックアウト
地域別支払い方法(インド向けUPI)
UPIの設定とテストの詳細については、India Payment Methodsページを参照してください。BNPL(Buy Now Pay Later)チェックアウト
BNPLの設定とテストの詳細については、Buy Now Pay Later (BNPL)ページを参照してください。既存の支払い方法を使用した即時チェックアウト
決済URLをすっきりさせる短縮リンク
支払い成功ページをスキップして即時リダイレクト
言語の強制指定
カスタムフィールドの収集
チェックアウトセッションのプレビュー
セッションを作成する前に価格、税金、合計金額を計算するには、Preview Checkout Sessionエンドポイントを使用します。サイトに正確な価格情報を表示する場合に便利です。プレビューされた
current_breakup.subtotalには、商品に適用される購買力平価とCharm Pricingがすでに反映されています。カートにサブスクリプション商品が含まれる場合、プレビューレスポンスには
next_billing_dateも返されます。これは、サブスクリプション作成前に表示できる、次回請求日のプレビューです。現在時刻を基準に計算され、トライアルが適用される場合はnow + trial period、それ以外の場合はnow + one payment frequencyです。単発商品のみのカートではこのフィールドは省略されます。これはプレビュー時点を基準にした推定値であり、正式なnext_billing_dateはサブスクリプションが有効になった時点で設定されます。プレビューには
trial_period_days(無料または有料の実効トライアル期間)とtrial_amount(割引後の1ユニットあたりのトライアル料金。価格通貨の最小単位)が返されます。trial_amountは有料トライアルの場合のみ存在し、無料トライアルまたはトライアルなしの場合はnullです。今日実際に支払うべき、税を含む合計額にはcurrent_breakupを使用してください。複数サブスクリプションのカートでは、サブスクリプションごとに1つのエントリを持つ
subscriptions配列も返されます。各エントリにはproduct_id、amount_due_now、tax_due_now、recurring_amount、recurring_tax、trial_period_days、next_billing_dateが含まれます。トップレベルのnext_billing_dateはカート内で最も早い日付で、トップレベルのtrial_period_daysとtrial_amountはnullです。金額はsubscriptionsとcurrent_breakupから読み取ってください。recurring_breakupは、更新日が異なる場合でもすべてのサブスクリプションの更新金額を合算するため、各更新額はsubscriptionsから読み取ってください。- Node.js SDK
- Python SDK
- REST API
Dynamic Linksからの移行
Dynamic Linksを使用している場合、Checkout Sessionsではより柔軟に対応できます。Dynamic Linksでは、顧客の完全な請求先住所を指定する必要がありました。Checkout Sessionsでは、手元にある情報だけを渡し、残りをチェックアウトフローに収集させることができます。 たとえば:- 顧客の請求先の国だけを指定し、残りの詳細をチェックアウトで収集する。
- またはすべての情報を指定し、
confirm: trueを設定して支払いページへ直接進む。