सदस्यता एकीकरण गाइड

​

आवश्यकताएँ

• Dodo Payments merchant account
• Dashboard में Developer → API Keys से API key, जिसे DODO_PAYMENTS_API_KEY में संग्रहीत किया गया हो
• Developer → Webhooks से webhook secret, जिसे DODO_PAYMENTS_WEBHOOK_KEY में संग्रहीत किया गया हो
• Products के अंतर्गत बनाया गया कम से कम एक subscription product

​

API Integration

​

Checkout Sessions

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: 'pdt_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: 'subscriber@example.com',
      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": "pdt_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "subscriber@example.com",
        "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: 'pdt_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: 'subscriber@example.com',
      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 Response

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

​

Webhooks

​

Subscription Event Types

1. subscription.active — Subscription सक्रिय हो गई
2. subscription.updated — Subscription का कोई field बदल गया
3. subscription.on_hold — Renewal या plan-change charge विफल हो गया
4. subscription.failed — Subscription creation विफल हुआ (terminal; ग्राहक को फिर से subscribe करना होगा)
5. subscription.renewed — Recurring charge सफल हुआ
6. subscription.past_due — Renewal विफल हुआ और grace period शुरू हुई; ग्राहक को past_due_ends_at तक access मिलता रहेगा
7. subscription.plan_changed — Plan को upgrade, downgrade या बदला गया
8. subscription.cancelled — Subscription cancel कर दी गई
9. subscription.expired — Subscription अपनी अवधि के अंत तक पहुँच गई

​

Payment Scenarios

1. subscription.active: mandate authorize होती है और subscription सक्रिय हो जाती है।
2. payment.succeeded: पहला charge confirm करता है। Checkout के 2–10 मिनट के भीतर इसकी अपेक्षा करें।

1. At trial start (checkout): Payment method authorize होने के बाद subscription.active fire होता है। अभी कोई recurring charge नहीं लिया जाता। पहला वास्तविक charge trial समाप्त होने तक स्थगित रहता है।
2. At trial end: Recurring amount charge किया जाता है और आपको payment.succeeded के साथ subscription.renewed प्राप्त होता है।

• subscription.renewed: प्रत्येक billing cycle पर fire होता है, जब renewal payment काटा जाता है, और हमेशा payment.succeeded के साथ आता है। इसमें updated next_billing_date भी शामिल होता है।

1. Subscription Failure

• subscription.failed - Mandate create न हो पाने के कारण subscription creation विफल हुआ।
• payment.failed - Failed payment दर्शाता है।

2. Subscription On Hold

• subscription.on_hold - Failed renewal payment या failed plan change charge के कारण subscription को on hold कर दिया गया है। यदि आपके business में grace period है, तो failed renewal पहले subscription को past_due (subscription.past_due) में ले जाता है और grace period समाप्त होने पर ही इसे on_hold (या आपकी grace period settings के आधार पर cancelled) में ले जाया जाता है। Subscription States देखें।
• जब कोई subscription on hold हो जाती है, तो payment method update किए जाने तक वह अपने-आप renew नहीं होगी।

​

subscription.failed vs. subscription.on_hold

​

Handling Subscription On Hold

​

When Subscriptions Go On Hold

• Renewal payment fails: अपर्याप्त funds, expired card या bank decline के कारण automatic renewal charge विफल हो जाता है
• Plan change charge fails: Plan upgrade/downgrade के दौरान immediate charge विफल हो जाता है
• Payment method authorization fails: Payment method को recurring charges के लिए authorize नहीं किया जा सकता

​

Reactivating Subscriptions from On Hold

1. शेष dues के लिए charge बनाता है
2. Charge के लिए invoice generate करता है
3. नए payment method का उपयोग करके payment process करता है
4. Payment सफल होने पर subscription को active state में फिर से सक्रिय करता है

// 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, {
  payment_method: { 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
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    payment_method={"type": "new", "return_url": "https://example.com/return"},
)

# For on_hold subscriptions, a charge is automatically created
if response.payment_id:
    print("Charge created for remaining dues:", response.payment_id)
    # Redirect customer to response.payment_link to complete payment

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { 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.'
  });
}

​

Sample Subscription Event Payload

​

Changing Subscription Plans

​

Proration Options

​

1. prorated_immediately

• वर्तमान billing cycle के unused हिस्से का समय शेष रहने के आधार पर prorated credit देता है। Credit base plan, quantity और किसी भी add-ons को cover करता है
• फिर नए plan, quantity और add-ons पर एक full cycle का charge लेता है। Charge स्वयं कभी prorated नहीं होता
• Net immediate charge = (full new cycle) minus (remaining fraction x full old cycle)। यदि credit बड़ा है, तो अंतर future renewals के लिए subscription-scoped credit के रूप में रखा जाता है
• Trial period के दौरान यह user को तुरंत नए plan पर switch कर देता है और customer से तुरंत charge लेता है

​

2. full_immediately

• Previous cycle के लिए कोई credit दिए बिना नए plan की पूरी subscription amount customer से charge करता है
• Upgrade या downgrade दोनों में customer नए plan की पूरी price शुरू से चुकाता है
• तब उपयोगी है जब पुराने plan में कितना समय बचा है, इसकी परवाह किए बिना पूरी amount charge करनी हो

​

3. difference_immediately

• Customer पुराने plan की price और नए plan की price के बीच का केवल अंतर चुकाता है
• Amount इस पर निर्भर नहीं करती कि cycle में बदलाव कब किया गया। Day 1 और day 29 पर एक ही upgrade की cost समान रहती है
• Upgrade करते समय customer से अंतर तुरंत charge किया जाता है। उदाहरण के लिए, $30/month → $80/month = तुरंत $50 charge
• Downgrade करते समय price difference subscription-scoped credit के रूप में store होता है और future renewals पर अपने-आप apply होता है। उदाहरण के लिए, $50/month → $20/month = $30 credit के रूप में store

​

4. do_not_bill

• Plan change तुरंत apply करता है, लेकिन बदलाव के समय कुछ भी charge नहीं करता। नया plan, quantity और add-ons तुरंत उपयोग किए जा सकते हैं
• क्योंकि अभी कोई charge नहीं लिया जाता, इसलिए upgrade customer को वर्तमान cycle के शेष समय के लिए higher plan free देता है। Downgrade तुरंत प्रभावी होता है और पहले से भुगतान किए गए cycle के unused हिस्से के लिए कोई credit नहीं मिलता
• do_not_bill के माध्यम से दिए गए add-ons को बाद के plan change पर credit नहीं किया जाता, क्योंकि उनका कभी billing नहीं हुआ। अगला change नई add-on quantity को पूरी तरह bill करता है
• Updated plan (और quantity/add-ons) को अगले scheduled renewal पर bill किया जाता है और original billing date सुरक्षित रहती है

​

Behavior

• जब आप इस API को invoke करते हैं, तो Dodo Payments आपके चुने हुए proration option के आधार पर तुरंत charge शुरू करता है
• prorated_immediately के साथ, current cycle के unused हिस्से का credit हर change पर calculate किया जाता है, चाहे upgrade हो या downgrade। यदि credit नए cycle के charge से अधिक है, तो शेष राशि subscription के credit balance में जोड़ दी जाती है। ये credits उसी subscription के लिए specific होते हैं और केवल उसी subscription के future recurring payments को offset करने के लिए उपयोग किए जाएंगे
• difference_immediately के साथ net हमेशा exact price difference होता है। Downgrade के लिए excess को subscription-scoped credit के रूप में store किया जाता है, ठीक prorated_immediately की तरह
• full_immediately option credit calculations को bypass करता है और नए plan की पूरी amount charge करता है
• do_not_bill option बदलाव को तुरंत apply करता है, लेकिन billing को preserved next renewal date तक स्थगित करता है

​

Charge Processing

• Plan change पर शुरू किया गया immediate charge आमतौर पर 2 मिनट से कम समय में process हो जाता है
• यदि यह immediate charge किसी भी कारण से विफल होता है, तो issue resolve होने तक subscription को अपने-आप on hold कर दिया जाता है

​

On-Demand Subscriptions

​

Subscription Billing के बारे में जानने योग्य मुख्य बातें

​

Related API Reference