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

​

आवश्यकताएँ

• 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 बनाना विफल हुआ (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 रद्द कर दी गई
9. subscription.expired — Subscription अपनी अवधि के अंत तक पहुँच गई

​

Payment Scenarios

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

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

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

1. Subscription Failure

• subscription.failed - Mandate बनाने में विफलता के कारण subscription बनाना विफल हुआ।
• payment.failed - विफल payment को दर्शाता है।

2. Subscription On Hold

• subscription.on_hold - Renewal payment या plan change charge विफल होने के कारण subscription on hold कर दी गई। यदि आपके business में grace period है, तो विफल 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 बनाम subscription.on_hold

​

Handling Subscription On Hold

​

When Subscriptions Go On Hold

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

​

Reactivating Subscriptions from On Hold

1. बकाया शेष राशि के लिए charge बनाता है
2. Charge के लिए invoice बनाता है
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 के अप्रयुक्त हिस्से का credit देता है, शेष समय के अनुसार prorate करके। Credit में base plan, quantity और add-ons शामिल होते हैं
• इसके बाद नए plan, quantity और add-ons के लिए पूर्ण cycle का charge लेता है। Charge स्वयं कभी prorate नहीं होता
• Net immediate charge = (पूर्ण नया cycle) minus (शेष fraction x पूर्ण पुराना cycle)। यदि credit बड़ा है, तो अंतर future renewals के लिए subscription-scoped credit के रूप में रखा जाता है
• Trial period के दौरान यह user को तुरंत नए plan पर switch करता है और ग्राहक से तुरंत charge लेता है

​

2. full_immediately

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

​

3. difference_immediately

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

​

4. do_not_bill

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

​

Behavior

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

​

Charge Processing

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

​

On-Demand Subscriptions

​

Subscription Billing के बारे में मुख्य बातें

​

Related API Reference