サブスクリプション統合ガイド

​

前提条件

• Dodo Paymentsのマーチャントアカウント
• ダッシュボードからのAPI認証情報（APIキーとWebhookシークレットキー）

​

API統合

​

チェックアウトセッション

import DodoPayments from 'dodopayments';

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

async function main() {
  const session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'prod_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: '[email protected]',
      name: 'Jane Doe',
    },
    return_url: 'https://example.com/success',
  });

  console.log(session.checkout_url);
}

main();

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": "prod_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "[email protected]",
        "name": "Jane Doe",
    },
    return_url="https://example.com/success",
)

print(session.checkout_url)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
  },
  body: JSON.stringify({
    product_cart: [
      { product_id: 'prod_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: '[email protected]',
      name: 'Jane Doe'
    },
    return_url: 'https://example.com/success'
  })
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const session = await response.json();
console.log(session.checkout_url);

​

APIレスポンス

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

​

Webhook

​

サブスクリプションイベントタイプ

1. subscription.active - サブスクリプションが正常にアクティブ化されました。
2. subscription.updated - サブスクリプションオブジェクトが更新されました（任意のフィールド変更時に発生します）。
3. subscription.on_hold - 更新に失敗したため、サブスクリプションが保留中になりました。
4. subscription.failed - マンダテ作成中にサブスクリプションの作成に失敗しました。
5. subscription.renewed - 次の請求期間のためにサブスクリプションが更新されました。

​

支払いシナリオ

1. subscription.active - サブスクリプションのアクティブ化を示します
2. payment.succeeded - 初回支払いを確認します：
   • 即時請求（0トライアル日）：2〜10分以内に期待されます
   • トライアル日：終了時
3. subscription.renewed - 支払いの控除と次のサイクルの更新を示します。（基本的に、サブスクリプション製品の支払いが控除されるたびに、subscription.renewedのWebhookがpayment.succeededと共に送信されます）

1. サブスクリプションの失敗

• subscription.failed - マンダテの作成に失敗したため、サブスクリプションの作成に失敗しました。
• payment.failed - 支払い失敗を示します。

2. サブスクリプションが保留中

• subscription.on_hold - 更新支払いの失敗またはプラン変更の請求の失敗により、サブスクリプションが保留中になりました。
• サブスクリプションが保留中になると、支払い方法が更新されるまで自動的に更新されません。

​

サブスクリプションが保留中の処理

​

サブスクリプションが保留中になるとき

• 更新支払いが失敗した場合：自動更新の請求が資金不足、カードの期限切れ、または銀行の拒否により失敗します
• プラン変更の請求が失敗した場合：プランのアップグレード/ダウングレード中の即時請求が失敗します
• 支払い方法の承認が失敗した場合：支払い方法が定期的な請求に対して承認できません

​

保留中のサブスクリプションの再アクティブ化

1. 残りの未払い分の請求を作成します
2. 請求のための請求書を生成します
3. 新しい支払い方法を使用して支払いを処理します
4. 支払いが成功した場合、サブスクリプションをactive状態に再アクティブ化します

// Webhook handler
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.on_hold') {
    const subscription = event.data;
    
    // Update subscription status in your database
    await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
    
    // Notify customer to update payment method
    await sendEmailToCustomer(subscription.customer_id, {
      subject: 'Payment Required - Subscription On Hold',
      message: 'Your subscription is on hold. Please update your payment method to continue service.'
    });
  }
  
  res.json({ received: true });
});

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  type: 'new',
  return_url: 'https://example.com/return'
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created for remaining dues:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
}

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  type: 'existing',
  payment_method_id: 'pm_abc123'
});

if (event.type === 'payment.succeeded') {
  const payment = event.data;
  
  // Check if this payment is for an on_hold subscription
  if (payment.subscription_id) {
    // Wait for subscription.active webhook to confirm reactivation
  }
}

if (event.type === 'subscription.active') {
  const subscription = event.data;
  
  // Update subscription status in your database
  await updateSubscriptionStatus(subscription.subscription_id, 'active');
  
  // Restore customer access
  await restoreCustomerAccess(subscription.customer_id);
  
  // Notify customer of successful reactivation
  await sendEmailToCustomer(subscription.customer_id, {
    subject: 'Subscription Reactivated',
    message: 'Your subscription has been reactivated successfully.'
  });
}

​

サンプルサブスクリプションイベントペイロード

​

サブスクリプションプランの変更

​

按分オプション

​

1. prorated_immediately

• 現在の請求サイクルの残り時間に基づいて按分額を計算します
• 古いプランと新しいプランの差額のみを顧客に請求します
• トライアル期間中は、ユーザーを新しいプランに即座に切り替え、顧客にすぐに請求します

​

2. full_immediately

• 新しいプランの全額を顧客に請求します
• 前のプランの残り時間やクレジットは無視します
• 請求サイクルをリセットしたり、按分に関係なく全額を請求したい場合に便利です

​

3. difference_immediately

• アップグレード時、顧客は2つのプランの金額の差額を即座に請求されます。
• 例えば、現在のプランが30ドルで、顧客が80ドルにアップグレードすると、50ドルが即座に請求されます。
• ダウングレード時、現在のプランの未使用額は内部クレジットとして追加され、将来のサブスクリプション更新に自動的に適用されます。
• 例えば、現在のプランが50ドルで、顧客が20ドルのプランに切り替えると、残りの30ドルがクレジットとして追加され、次の請求サイクルに使用されます。

​

挙動

• このAPIを呼び出すと、Dodo Paymentsは選択した按分オプションに基づいて即座に請求を開始します
• プラン変更がダウングレードで、prorated_immediatelyを使用する場合、クレジットが自動的に計算され、サブスクリプションのクレジット残高に追加されます。これらのクレジットはそのサブスクリプションに特有で、同じサブスクリプションの将来の定期的な支払いの相殺にのみ使用されます
• full_immediatelyオプションはクレジット計算をバイパスし、新しいプランの全額を請求します

​

請求処理

• プラン変更時に開始される即時請求は通常、2分以内に処理が完了します
• この即時請求が何らかの理由で失敗した場合、サブスクリプションは問題が解決されるまで自動的に保留中になります

​

オンデマンドサブスクリプション