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

​

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

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

​

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"
}

​

Webhooks

​

सब्सक्रिप्शन इवेंट प्रकार

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

​

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

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

1. Trial शुरू होने पर (checkout): payment method अधिकृत होने के बाद subscription.active fire होता है। अभी कोई recurring charge नहीं लिया जाता। पहला वास्तविक charge trial समाप्त होने तक टाल दिया जाता है।
2. Trial समाप्त होने पर: 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 बनाने में विफलता के कारण subscription creation विफल हुआ।
• payment.failed - विफल payment को दर्शाता है।

2. Subscription On Hold

• subscription.on_hold - renewal payment या plan change charge विफल होने के कारण subscription को on hold कर दिया गया है।
• जब subscription on hold हो जाती है, तो payment method update किए जाने तक वह अपने-आप renew नहीं होगी।

​

subscription.failed बनाम subscription.on_hold

​

Subscription On Hold को संभालना

​

Subscriptions कब 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 नहीं किया जा सकता

​

On Hold से Subscriptions को फिर से सक्रिय करना

1. शेष dues के लिए 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, {
  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,
    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, {
  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

​

Subscription Plans बदलना

​

Proration Options

​

1. prorated_immediately

• मौजूदा billing cycle में बचे समय के आधार पर prorated amount calculate करता है
• Customer से पुराने और नए plan के बीच का अंतर ही charge करता है
• Trial period के दौरान, यह user को तुरंत नए plan पर switch कर देगा और customer से तुरंत charge लेगा

​

2. full_immediately

• नए plan के लिए customer से पूरी subscription amount charge करता है
• पिछले plan के बचे समय या credits को अनदेखा करता है
• तब उपयोगी है जब आप billing cycle reset करना चाहते हैं या proration की परवाह किए बिना पूरी amount charge करना चाहते हैं

​

3. difference_immediately

• Upgrade करते समय, customer से दोनों plan amounts के बीच का अंतर तुरंत charge किया जाता है।
• उदाहरण के लिए, यदि वर्तमान plan 30 Dollars का है और customer 80 Dollars वाले plan पर upgrade करता है, तो उससे तुरंत $50 charge किए जाते हैं।
• Downgrade करते समय, वर्तमान plan की unused amount को internal credit के रूप में जोड़ा जाता है और future subscription renewals पर अपने-आप लागू किया जाता है।
• उदाहरण के लिए, यदि वर्तमान plan 50 Dollars का है और customer 20 Dollars वाले plan पर switch करता है, तो शेष $30 credit के रूप में जोड़े जाते हैं और अगले billing cycle में उपयोग किए जाते हैं।

​

4. do_not_bill

• Plan change को तुरंत लागू करता है, लेकिन change के समय कुछ भी charge नहीं करता।
• Updated plan (और quantity/add-ons) को अगले scheduled renewal पर bill किया जाता है और मूल billing date बरकरार रहती है।

​

Behavior

• जब आप इस API को invoke करते हैं, तो Dodo Payments आपके चुने हुए proration option के आधार पर तुरंत charge शुरू करता है
• यदि plan change downgrade है और आप prorated_immediately का उपयोग करते हैं, तो credits अपने-आप calculate होकर subscription के credit balance में जोड़े जाएंगे। ये credits उसी subscription के लिए specific हैं और केवल उसी subscription के future recurring payments को offset करने के लिए उपयोग किए जाएंगे
• full_immediately option credit calculations को bypass करता है और नए plan की पूरी amount charge करता है

​

Charge Processing

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

​

On-Demand Subscriptions

​

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

​

Related API Reference