Integration Guide

Checkout Sessions

一回限りの決済とサブスクリプションに対応した、安全なホスト型checkoutを作成します。

Payment Links

コードを書かずに決済を受け付けるためのURLを共有します。

Webhooks

決済イベントを受け取り、注文を処理します。

API Reference

すべてのendpointのドキュメントとライブテストを利用できます。

前提条件

開始する前に、次のものが必要です。

Dodo Payments アカウント。
少なくとも 1 つの製品。ダッシュボードの Products で作成します。0 以外の価格を設定したサブスクリプション製品では、顧客が支払う通貨の subscription minimum を満たす必要があります。USD の場合は $1.00 です。USD、EUR、GBP 以外の通貨も、少なくとも $1.00 相当である必要があります。$0 のサブスクリプションにも対応しています。
API key。ダッシュボードの Developer → API Keys で作成し、DODO_PAYMENTS_API_KEY 環境変数に保存します。構築中は test mode でキーを作成してください。このページの例は test mode を使用しており、test mode のキーは test mode に対してのみ機能します。Authentication を参照してください。
使用する言語の SDK。Node.js SDK には Node.js 20 以降、Python SDK には Python 3.9 以降、Go SDK には Go 1.22 以降が必要です。cURL の例では SDK は必要ありません。

npm install dodopayments

pip install dodopayments

go get github.com/dodopayments/dodopayments-go

webhook example では standardwebhooks パッケージも使用します。npm install standardwebhooks でインストールしてください。

Integration Path を選択する

Path	使用する状況	Guide
Checkout sessions	サーバーからホスト型の checkout を作成する場合。ほとんどの integration で推奨される path です。	Checkout Sessions
Overlay checkout	Web ページ上で checkout を modal として開く場合。	Overlay Checkout
Inline checkout	独自の注文概要の横など、ページレイアウト内に checkout を埋め込む場合。	Inline Checkout
Static payment links	コードなしで共有可能な URL が必要な場合。	Payment Links
Mobile checkout SDKs	ネイティブ Android、iOS、React Native、または Flutter アプリを構築する場合。	Mobile Integration

Overlay checkout と inline checkout は Web ページでのみ実行されます。ネイティブモバイルアプリでは、サーバー上で checkout session を作成し、mobile checkout SDK でその checkout_url を開いてください。この integration の構築を coding agent に依頼するには、Agent Plugin をインストールしてください。

Checkout Sessions

安全なホスト型 checkout experience を作成します。サーバー上で session を作成し、返された checkout_url に顧客を redirect します。

各 checkout_url は 1 回だけ使用でき、24 時間後、または confirm: true を渡した場合は 15 分後に期限切れになります。confirm: true を使用する場合は、必須フィールドをすべて指定する必要があります。顧客ごと、支払い試行ごとに新しい session を作成してください。

Checkout Session を作成する

Node.js SDK
Python SDK
cURL

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  customer: { email: 'customer@example.com', name: 'John Doe' },
  return_url: 'https://yourapp.com/checkout/success',
});

console.log(session.checkout_url);

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",  # defaults to "live_mode"
)

session = client.checkout_sessions.create(
    product_cart=[{"product_id": "pdt_123", "quantity": 1}],
    customer={"email": "customer@example.com", "name": "John Doe"},
    return_url="https://yourapp.com/checkout/success",
)

print(session.checkout_url)

curl -X POST https://test.dodopayments.com/checkouts \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [{"product_id": "pdt_123", "quantity": 1}],
    "customer": {"email": "customer@example.com", "name": "John Doe"},
    "return_url": "https://yourapp.com/checkout/success"
  }'

Checkout に redirect する

session の作成後、顧客を checkout_url に redirect します。

window.location.href = session.checkout_url;

高度なカスタマイズについては、完全版の Checkout Sessions guide と API Reference を参照してください。

エラーを処理する

リクエストが失敗すると、API は HTTP status code と、code および message を含む JSON body を返します。エラー処理の分岐には message ではなく code を使用してください。各 code、その原因、解決方法については Error Codes を参照してください。支払いの失敗は別途報告されます。支払いの status は failed となり、error_code に理由が示され、payment.failed webhook が届きます。retry するかどうかを判断するには、Handle Payment Failures を参照してください。

Payment Links

payment link は、製品の checkout を開く URL です。コードを記述せずに支払いを回収できます。query parameters により顧客情報を事前入力し、checkout form を制御できます。顧客が link を開くと、checkout は parameters を session に保存し、URL を session parameter に短縮するため、ページを refresh しても情報が保持されます。

Static Payment Links

static payment link は、1 回作成して複数回共有する URL です。base URL は次のとおりです。

https://checkout.dodopayments.com/buy/{product_id}

checkout をカスタマイズするには query parameters を追加します。

integer

デフォルト:"1"

購入するアイテム数。

string

必須

Payment Links は redirect_url を使用します。Checkout Sessions API は同じ用途に return_url を使用します。支払い後の redirect 先 URL。Dodo Payments は支払いの詳細を query parameters として追加します。例: https://example.com/?payment_id=pay_ts2ySpzg07phGeBZqePbH&status=succeeded&email=customer%40example.com。製品が license keys を発行する場合は、license_key parameter も追加され、複数の key はカンマで区切られます。

string

支払い通貨を指定します。デフォルトは billing country の通貨です。

boolean

デフォルト:"true"

通貨 selector を表示または非表示にします。

boolean

デフォルト:"true"

discounts section を表示または非表示にします。顧客が coupon codes を入力できないようにするには、false に設定します。

number

請求額を major currency units で固定します。例: $12.50 の場合は 12.5。Pay What You Want products でのみ機能し、製品の minimum price 未満の場合は無視されます。

paymentAmount は major currency units を使用します（12.5 は $12.50）。Checkout Sessions API の field product_cart[].amount は smallest currency unit を使用します（1250 は $12.50）。Dynamic Pricing を参照してください。

string

カスタム metadata fields。例: metadata_orderId=123。

顧客情報を事前入力する

checkout をスムーズにするには、顧客 fields を query parameters として追加します。

string

顧客のフルネーム（firstName または lastName が指定されている場合は無視されます）。

string

顧客の first name。

string

顧客の last name。

string

顧客の email address。

string

顧客の国（ISO 3166-1 alpha-2 code）。

string

Street address。

string

City。

string

State または province。

string

Postal または ZIP code。

Form fields を無効にする

顧客が事前入力された情報を変更できないようにするには、値を指定し、対応する disable... flag を true に設定して field を無効にします。

?email=alice@example.com&disableEmail=true

Field	Disable Flag	Required Parameter
Full Name	`disableFullName`	`fullName`
First Name	`disableFirstName`	`firstName`
Last Name	`disableLastName`	`lastName`
Email	`disableEmail`	`email`
Country	`disableCountry`	`country`
Address Line	`disableAddressLine`	`addressLine`
City	`disableCity`	`city`
State	`disableState`	`state`
ZIP Code	`disableZipCode`	`zipCode`

Static Payment Link の例

https://checkout.dodopayments.com/buy/pdt_123?quantity=1&email=alice@example.com&disableEmail=true&redirect_url=https://example.com/success

fields を無効にすると、誤った変更を防ぎ、データの整合性を確保できます。

Dynamic Payment Links（非推奨）

POST /payments endpoint と POST /subscriptions endpoint は非推奨です。新しい integration では、代わりに Checkout Sessions を使用してください。

dynamic payment links を使用する既存の integration では、payment_link: true を Create One-Time Payment または Create Subscription に渡して link を作成します。以下の例では one-time payment link を作成します。サブスクリプションについては、Subscription Integration Guide を参照してください。

Node.js SDK
Python SDK
Go SDK

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode',
});

const payment = await client.payments.create({
  payment_link: true,
  billing: {
    city: 'San Francisco',
    country: 'US',
    state: 'CA',
    street: '123 Main St',
    zipcode: '94102',
  },
  customer: { email: 'customer@example.com', name: 'John Doe' },
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
});

console.log(payment.payment_link);

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get("DODO_PAYMENTS_API_KEY"),
    environment="test_mode",
)

payment = client.payments.create(
    payment_link=True,
    billing={
        "city": "San Francisco",
        "country": "US",
        "state": "CA",
        "street": "123 Main St",
        "zipcode": "94102",
    },
    customer={"email": "customer@example.com", "name": "John Doe"},
    product_cart=[{"product_id": "pdt_123", "quantity": 1}],
)

print(payment.payment_link)

package main

import (
	"context"
	"fmt"

	"github.com/dodopayments/dodopayments-go"
	"github.com/dodopayments/dodopayments-go/option"
)

func main() {
	// Reads DODO_PAYMENTS_API_KEY from the environment.
	client := dodopayments.NewClient(option.WithEnvironmentTestMode())

	payment, err := client.Payments.New(context.Background(), dodopayments.PaymentNewParams{
		PaymentLink: dodopayments.F(true),
		Billing: dodopayments.F(dodopayments.BillingAddressParam{
			City:    dodopayments.F("San Francisco"),
			Country: dodopayments.F(dodopayments.CountryCodeUs),
			State:   dodopayments.F("CA"),
			Street:  dodopayments.F("123 Main St"),
			Zipcode: dodopayments.F("94102"),
		}),
		Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](dodopayments.NewCustomerParam{
			Email: dodopayments.F("customer@example.com"),
			Name:  dodopayments.F("John Doe"),
		}),
		ProductCart: dodopayments.F([]dodopayments.OneTimeProductCartItemParam{{
			ProductID: dodopayments.F("pdt_123"),
			Quantity:  dodopayments.F(int64(1)),
		}}),
	})
	if err != nil {
		panic(err.Error())
	}

	fmt.Println(payment.PaymentLink)
}

Webhooks

Webhooks は、支払いが成功または失敗したときにサーバーへ通知するため、注文を fulfill できます。

Webhook Endpoint を作成する

ダッシュボードで Developer → Webhooks に移動し、endpoint URL を追加します。endpoint の signing secret を DODO_PAYMENTS_WEBHOOK_KEY 環境変数にコピーします。 Next.js を使用した例を示します。

app/api/webhooks/dodo/route.ts

import { Webhook } from "standardwebhooks";

const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY!);

export async function POST(request: Request) {
  const rawBody = await request.text();

  const webhookHeaders = {
    "webhook-id": request.headers.get("webhook-id") ?? "",
    "webhook-signature": request.headers.get("webhook-signature") ?? "",
    "webhook-timestamp": request.headers.get("webhook-timestamp") ?? "",
  };

  try {
    await webhook.verify(rawBody, webhookHeaders);
  } catch {
    return new Response("Invalid signature", { status: 400 });
  }

  const payload = JSON.parse(rawBody);

  switch (payload.type) {
    case "payment.succeeded":
      // Fulfill the order
      break;
    case "payment.failed":
      // Notify the customer
      break;
  }

  return new Response(null, { status: 200 });
}

Webhook の実装は Standard Webhooks specification に準拠しています。

Listen する Events

少なくとも、one-time payment flow では次の events を listen してください。

Event	発生するタイミング	実行する処理
`payment.succeeded`	支払いが正常に処理されたとき。	注文を fulfill します。access を付与し、product を provision し、receipt を送信します。
`payment.failed`	支払い試行が失敗したとき（カードの拒否、error など）。	顧客に通知し、retry を促します。
`payment.processing`	支払いは承認されたものの、まだ処理中のとき（async methods）。	fulfill する前に `payment.succeeded` または `payment.failed` を待ちます。
`payment.cancelled`	完了前に支払いがキャンセルされたとき。	保持している state を解放し、注文を abandoned としてマークします。

常に browser redirect ではなく webhook の payment.succeeded で fulfill してください。顧客が tab を閉じると redirect は見逃される可能性がありますが、webhook は acknowledge されるまで retry されます。

license keys を販売する場合は、license_key.created も処理してください。subscription、entitlement、credit、recovery、dunning events を含む完全な events の一覧については、Webhook Event Guide を参照してください。完全な Next.js および TypeScript の例については、demo repository とその live deployment を参照してください。

Currency と Billing Address

特定の通貨で請求するには、checkout session の作成時に billing_currency と billing_address.country を渡します。省略すると、Adaptive Currency が顧客の IP address から通貨と国を選択します。これは意図した請求通貨と異なる場合があります。 Pay What You Want の金額は製品の base currency で指定し、USD、GBP、または EUR である必要があります。別の通貨で固定額を回収するには、live exchange rates で base price を変換する Adaptive Currency、または通貨ごとに固定価格を設定する Localized Pricing を使用します。Localized Pricing は Pay What You Want には対応していません。

One-Click Repeat Purchase

保存済みの payment method を使用して returning customer に請求するには、その payment_method_id と confirm: true を渡します。payment_method_id は confirm が true の場合にのみ受け付けられ、既存の顧客の customer_id も渡す必要があります。confirm が true であるため、完全な billing_address、または minimal_address が true の場合に限り country と zipcode のみを渡す必要があります。session は保存済みの payment method に直接請求するため、checkout_url を返しません。支払いが成功したかどうかは webhooks で確認してください。

const session = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
  customer: { customer_id: 'cus_123' },
  payment_method_id: 'pm_123',
  billing_address: {
    country: 'US',
    state: 'CA',
    city: 'San Francisco',
    street: '123 Main St',
    zipcode: '94102',
  },
  confirm: true,
});

Checkout Sessions

高度なカスタマイズ options を含む完全な guide。

Overlay Checkout

checkout を modal overlay としてページに埋め込みます。

Inline Checkout

checkout をページレイアウトに直接埋め込みます。

Subscription Integration

定期 billing を設定します。

Webhook Event Guide

すべての webhook events の完全な一覧。

API Reference

Checkout Sessions API documentation。