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

पूर्वापेक्षाएँ

डोडो पेमेंट्स API को एकीकृत करने के लिए, आपको आवश्यकता होगी:

एक डोडो पेमेंट्स व्यापारी खाता
डैशबोर्ड से API क्रेडेंशियल्स (API कुंजी और वेबहुक गुप्त कुंजी)

पूर्वापेक्षाओं पर अधिक विस्तृत गाइड के लिए, इस अनुभाग की जांच करें।

API एकीकरण

चेकआउट सत्र

Use Checkout Sessions to sell subscription products with a secure, hosted checkout. Pass your subscription product in product_cart and redirect customers to the returned checkout_url.

Mixed Checkout: आप एक ही चेकआउट सत्र में subscription उत्पादों को एक-बार के उत्पादों के साथ मिला सकते हैं। यह सेटअप शुल्क के साथ subscription, हार्डवेयर बंडल्स के साथ SaaS, और अन्य उपयोग-मामलों को सक्षम करता है। उदाहरणों के लिए Checkout Sessions guide देखें।

Node.js SDK
Python SDK
REST 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: '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": "prod_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: 'prod_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 प्रतिक्रिया

निम्नलिखित प्रतिक्रिया का एक उदाहरण है:

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

ग्राहक को checkout_url पर पुनर्निर्देशित करें।

वेबहुक

सदस्यताओं को एकीकृत करते समय, आपको सदस्यता जीवनचक्र को ट्रैक करने के लिए वेबहुक प्राप्त होंगे। ये वेबहुक आपको सदस्यता की स्थिति और भुगतान परिदृश्यों को प्रभावी ढंग से प्रबंधित करने में मदद करते हैं। अपने वेबहुक एंडपॉइंट को सेट करने के लिए, कृपया हमारे विस्तृत एकीकरण गाइड का पालन करें।

सदस्यता घटना प्रकार

निम्नलिखित वेबहुक घटनाएँ सदस्यता स्थिति परिवर्तनों को ट्रैक करती हैं:

subscription.active - Subscription सफलतापूर्वक सक्रिय हो गई है।
subscription.updated - Subscription ऑब्जेक्ट अपडेट हो गया था (कोई भी फ़ील्ड बदलते ही ट्रिगर होता है)।
subscription.on_hold - असफल नवीनीकरण के कारण Subscription को होल्ड पर रखा गया है।
subscription.failed - मैनडेट बनाने के दौरान Subscription निर्माण विफल हो गया।
subscription.renewed - Subscription अगले बिलिंग अवधि के लिए नवीनीकृत कर दी गई है।

विश्वसनीय सदस्यता जीवनचक्र प्रबंधन के लिए, हम इन सदस्यता घटनाओं को ट्रैक करने की सिफारिश करते हैं।

किसी भी subscription परिवर्तनों के बारे में वास्तविक समय सूचनाएं प्राप्त करने के लिए subscription.updated का उपयोग करें, जिससे आपका एप्लिकेशन स्टेट API को पोल किए बिना सिंक में बना रहता है।

भुगतान परिदृश्य

सफल भुगतान प्रवाह जब एक भुगतान सफल होता है, तो आपको निम्नलिखित वेबहुक प्राप्त होंगे:

subscription.active - Subscription सक्रियता को दर्शाता है
payment.succeeded - प्रारंभिक भुगतान की पुष्टि करता है:
- तत्काल बिलिंग (0 ट्रायल दिन): 2-10 मिनट के भीतर अपेक्षित
- ट्रायल दिनों के लिए: जब भी वह समाप्त होता है
subscription.renewed - अगले चक्र के लिए भुगतान कटौती और नवीनीकरण को दर्शाता है। (मूलतः, जब भी subscription उत्पादों के लिए भुगतान कटता है, आपको subscription.renewed webhook मिलेगा payment.succeeded के साथ)

भुगतान विफलता परिदृश्य

Subscription Failure

subscription.failed - Subscription निर्माण मैनडेट बनाने में विफल रहने के कारण असफल रहा।
payment.failed - असफल भुगतान को दर्शाता है।

Subscription On Hold

subscription.on_hold - Subscription को असफल नवीनीकरण भुगतान या असफल योजना परिवर्तन शुल्क के कारण होल्ड पर रखा गया है।
जब Subscription होल्ड पर जाती है, तब तक यह स्वचालित रूप से नवीनीकृत नहीं होगी जब तक भुगतान विधि को अपडेट न किया जाए।

Best Practice: कार्यान्वयन को सरल बनाने के लिए, हम सलाह देते हैं कि आप Subscription जीवनचक्र प्रबंधन के लिए मुख्यतः Subscription ईवेंट्स को ट्रैक करें।

For a complete walkthrough of reading error_code/error_message, deciding when to retry, and surfacing failures to customers, see Handle Payment Failures.

`subscription.failed` vs. `subscription.on_hold`

इन दो घटनाओं को समझना आसान है, लेकिन इनके लिए अलग-अलग तरीके की हैंडलिंग की आवश्यकता होती है:

इवेंट	कब ट्रिगर होता है	स्थिति	रिकवर करने योग्य?	क्या करना है
`subscription.failed`	प्रारंभिक अनुमति सब्सक्रिप्शन निर्माण पर नहीं बनाई जा सकी	`failed`	नहीं — अंतिम	पहुंच प्रदान न करें। ग्राहक से एक नया सब्सक्रिप्शन शुरू करने के लिए कहें, एक अलग भुगतान विधि के साथ।
`subscription.on_hold`	एक नवीनीकरण भुगतान (या प्लान-परिवर्तन चार्ज) पहले से सक्रिय सब्सक्रिप्शन पर विफल हो गया	`on_hold`	हाँ	भुगतान विधि को अपडेट करके पुनः प्राप्त करें; नीचे Handling Subscription On Hold देखें।

subscription.failed अंतिम है — सब्सक्रिप्शन पुनः सक्रिय नहीं किया जा सकता। ग्राहक को एक नया सब्सक्रिप्शन बनाना होगा। जब यह घटना होती है तो कभी भी अधिकार न दें।

सब्सक्रिप्शन ऑन होल्ड को संभालना

जब सब्सक्रिप्शन on_hold स्थिति में जाता है, तो आपको इसे पुनः सक्रिय करने के लिए भुगतान विधि को अपडेट करना होगा। यह अनुभाग बताता है कि सब्सक्रिप्शन कब होल्ड पर जाते हैं और उन्हें कैसे संभालें।

जब सब्सक्रिप्शन होल्ड पर जाते हैं

एक सब्सक्रिप्शन होल्ड पर रखा जाता है जब:

नवीनीकरण भुगतान विफल: अपर्याप्त धनराशि, एक्सपायर कार्ड, या बैंक की अस्वीकृति के कारण स्वचालित नवीनीकरण चार्ज विफल हो जाता है
प्लान परिवर्तन चार्ज विफल: प्लान अपग्रेड/डाउनग्रेड के दौरान तत्काल चार्ज विफल हो जाता है
भुगतान विधि प्राधिकरण विफल: आवर्ती शुल्कों के लिए भुगतान विधि को प्राधिकृत नहीं किया जा सकता

on_hold स्थिति में सब्सक्रिप्शन स्वचालित रूप से नवीनीकरण नहीं करेगा। आपको सब्सक्रिप्शन को पुनः सक्रिय करने के लिए भुगतान विधि को अपडेट करना होगा।

ऑन होल्ड से सब्सक्रिप्शन पुनः सक्रिय करना

on_hold स्थिति से सब्सक्रिप्शन को पुनः सक्रिय करने के लिए, Update Payment Method API का उपयोग करें। यह स्वचालित रूप से:

शेष बकाया के लिए चार्ज बनाता है
चार्ज के लिए एक इनवॉइस उत्पन्न करता है
नई भुगतान विधि का उपयोग करके भुगतान प्रक्रिया करता है
सफल भुगतान पर सब्सक्रिप्शन को active स्थिति में पुनः सक्रिय करता है

Handle subscription.on_hold webhook

जब आपको एक subscription.on_hold वेबहूक प्राप्त होता है, तो अपने ऐप्लिकेशन की स्थिति अपडेट करें और ग्राहक को सूचित करें:

// 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 payment method

जब ग्राहक अपनी भुगतान विधि को अपडेट करने के लिए तैयार हो, तो Update Payment Method API कॉल करें:

// 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'
});

Monitor webhook events

भुगतान विधि को अपडेट करने के बाद, इन वेबहूक घटनाओं की निगरानी करें:

payment.succeeded - शेष बकाया के लिए चार्ज सफल हुआ
subscription.active - सब्सक्रिप्शन पुनः सक्रिय किया गया है

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.'
  });
}

सैंपल सब्सक्रिप्शन इवेंट पेलोड

प्रॉपर्टी	प्रकार	आवश्यक	विवरण
`business_id`	string	हाँ	व्यवसाय के लिए अद्वितीय पहचानकर्ता
`timestamp`	string	हाँ	इवेंट कब हुई इसका समय (आवश्य नहीं कि जब उसे डिलिवर किया गया हो)
`type`	string	हाँ	इवेंट का प्रकार। Event Types देखें
`data`	object	हाँ	मुख्य डेटा पेलोड। Data Object देखें

सब्सक्रिप्शन प्लान बदलना

आप सब्सक्रिप्शन प्लान को अपग्रेड या डाउनग्रेड कर सकते हैं चेंज प्लान API एंडपॉइंट का उपयोग करके। यह आपको सब्सक्रिप्शन के उत्पाद, मात्रा को बदलने और प्ररेशन को संभालने की अनुमति देता है।

Change Plan API Reference

सब्सक्रिप्शन प्लान बदलने के बारे में विस्तृत जानकारी के लिए, कृपया हमारे चेंज प्लान API दस्तावेज़ देखें।

प्ररेशन विकल्प

सब्सक्रिप्शन प्लान बदलते समय, आपके पास तात्कालिक चार्ज को संभालने के दो विकल्प हैं:

1. `prorated_immediately`

वर्तमान बिलिंग चक्र में शेष समय के आधार पर अनुपातिक राशि की गणना करता है
ग्राहक से केवल पुराने और नए प्लान के बीच का अंतर चार्ज करता है
एक परीक्षण अवधि के दौरान, यह तुरंत उपयोगकर्ता को नए प्लान पर बदल देगा, ग्राहक से तुरंत शुल्क लेता है

2. `full_immediately`

नए प्लान के लिए ग्राहक से पूरा सब्सक्रिप्शन राशि चार्ज करता है
पिछले प्लान के शेष समय या क्रेडिट को अनदेखा करता है
उपयोगी है जब आप बिलिंग चक्र को रीसेट करना चाहते हैं या प्ररेशन के बावजूद पूरा राशि चार्ज करना चाहते हैं

3. `difference_immediately`

अपग्रेड करते समय, ग्राहक से तुरंत दोनों प्लान की राशि के अंतर को चार्ज किया जाता है।
उदाहरण के लिए, यदि वर्तमान प्लान 30 डॉलर है और ग्राहक 80 डॉलर में अपग्रेड करता है, तो उन्हें $50 तुरंत चार्ज किया जाता है।
डाउनग्रेड करते समय, वर्तमान प्लान से अनुपयोगी राशि को आंतरिक क्रेडिट के रूप में जोड़ा जाता है और इसे भविष्य में सब्सक्रिप्शन नवीनीकरणों के लिए स्वचालित रूप से लागू किया जाता है।
उदाहरण के लिए, यदि वर्तमान प्लान 50 डॉलर है और ग्राहक 20 डॉलर के प्लान पर बदलता है, तो शेष $30 क्रेडिट किया जाता है और इसे अगले बिलिंग चक्र की ओर इस्तेमाल किया जाता है।

व्यवहार

जब आप इस API को बुलाते हैं, Dodo Payments आपकी चुनी गई प्ररेशन विकल्प के आधार पर तुरंत एक चार्ज प्रारंभ करता है
यदि प्लान परिवर्तन एक डाउनग्रेड है और आप prorated_immediately का उपयोग करते हैं, तो क्रेडिट को स्वचालित रूप से गणना की जाएगी और सब्सक्रिप्शन की क्रेडिट बैलेंस में जोड़ा जाएगा। ये क्रेडिट विशेष रूप से उसी सब्सक्रिप्शन के भविष्य के आवर्ती भुगतान को समायोजित करने के लिए उपयोग किए जाएंगे
full_immediately विकल्प क्रेडिट गणनाओं को बायपास करता है और नए प्लान की पूरी राशि का चार्ज करता है

अपने प्ररेशन विकल्प को सावधानीपूर्वक चुनें: UNUSED समय को ध्यान में रखते हुए उचित बिलिंग के लिए prorated_immediately का उपयोग करें, या जब आप वर्तमान बिलिंग चक्र के बावजूद पूर्ण नए प्लान की राशि चार्ज करना चाहते हैं तो full_immediately का उपयोग करें।

चार्ज प्रोसेसिंग

योजना परिवर्तन पर तात्कालिक रूप से आरंभ किया गया चार्ज आम तौर पर 2 मिनट से कम में प्रोसेसिंग पूरी कर लेता है
यदि किसी कारण से यह तात्कालिक चार्ज विफल हो जाता है, तो सब्सक्रिप्शन को स्वचालित रूप से होल्ड पर रखा जाता है जब तक कि यह समस्या हल नहीं हो जाती

ऑन-डिमांड सब्सक्रिप्शन

ऑन-डिमांड सब्सक्रिप्शन आपको ग्राहकों को विशेष रूप से शुल्क देने की अनुमति देते हैं, न कि केवल एक निश्चित अनुसूची पर। यह सुविधा सभी खातों के लिए उपलब्ध है।

एक ऑन-डिमांड सब्सक्रिप्शन बनाने के लिए: एक ऑन-डिमांड सब्सक्रिप्शन बनाने के लिए, POST /subscriptions एपीआई एंडपॉइंट का उपयोग करें और अपने अनुरोध में on_demand फ़ील्ड को शामिल करें। यह आपको तत्काल चार्ज के बिना एक भुगतान विधि को अधिकृत करने या एक विशेष प्रारंभिक मूल्य सेट करने की अनुमति देता है। एक ऑन-डिमांड सब्सक्रिप्शन को चार्ज करने के लिए: अगले चार्ज के लिए, POST /subscriptions//charge एंडपॉइंट का उपयोग करें और उस लेनदेन के लिए ग्राहक से चार्ज करने की राशि निर्दिष्ट करें।

पूरा चरण-दर-चरण मार्गदर्शिका—जिसमें अनुरोध/प्रतिक्रिया उदाहरण, सुरक्षित पुनः प्रयास नीतियां, और वेबहूक हैंडलिंग शामिल है—देखें On-Demand Subscriptions Guide।

Create Subscription

सब्सक्रिप्शन उत्पादों को बनाने और सब्सक्रिप्शन जीवनचक्र को प्रबंधित करने के लिए एपीआई संदर्भ

Change Subscription Plan

प्ररेशन विकल्पों के साथ सब्सक्रिप्शन प्लान को अपग्रेड, डाउनग्रेड या बदलने के लिए एपीआई संदर्भ

Update Payment Method

भुगतान विधियों को अपडेट करने और ऑन-होल्ड सब्सक्रिप्शन को पुनः सक्रिय करने के लिए एपीआई संदर्भ

Patch Subscription

सब्सक्रिप्शन विवरण और कॉन्फ़िगरेशन को अपडेट करने के लिए एपीआई संदर्भ

अंतिम संशोधन 18 जून 2026

प्रीवियस

भुगतान विफलताओं को संभालेंWebhook और API से विफल भुगतानों का पता लगाएं, विफलता का कारण पढ़ें, इसे सुरक्षित रूप से ग्राहकों तक पहुंचाएं, और पुनः प्रयास करने या नए भुगतान विधि एकत्र करने का निर्णय लें।

नेक्स्ट

​पूर्वापेक्षाएँ

​API एकीकरण

​चेकआउट सत्र

​API प्रतिक्रिया

​वेबहुक

​सदस्यता घटना प्रकार

​भुगतान परिदृश्य

​subscription.failed vs. subscription.on_hold

​सब्सक्रिप्शन ऑन होल्ड को संभालना

​जब सब्सक्रिप्शन होल्ड पर जाते हैं

​ऑन होल्ड से सब्सक्रिप्शन पुनः सक्रिय करना

​सैंपल सब्सक्रिप्शन इवेंट पेलोड

​सब्सक्रिप्शन प्लान बदलना

Change Plan API Reference

​प्ररेशन विकल्प

​1. prorated_immediately

​2. full_immediately

​3. difference_immediately

​व्यवहार

​चार्ज प्रोसेसिंग

​ऑन-डिमांड सब्सक्रिप्शन

​संबंधित एपीआई संदर्भ

Create Subscription

Change Subscription Plan

Update Payment Method

Patch Subscription

पूर्वापेक्षाएँ

API एकीकरण

चेकआउट सत्र

API प्रतिक्रिया

वेबहुक

सदस्यता घटना प्रकार

भुगतान परिदृश्य

`subscription.failed` vs. `subscription.on_hold`

सब्सक्रिप्शन ऑन होल्ड को संभालना

जब सब्सक्रिप्शन होल्ड पर जाते हैं

ऑन होल्ड से सब्सक्रिप्शन पुनः सक्रिय करना

सैंपल सब्सक्रिप्शन इवेंट पेलोड

सब्सक्रिप्शन प्लान बदलना

प्ररेशन विकल्प

1. `prorated_immediately`

2. `full_immediately`

3. `difference_immediately`

व्यवहार

चार्ज प्रोसेसिंग

ऑन-डिमांड सब्सक्रिप्शन

संबंधित एपीआई संदर्भ