Skip to main content

अवलोकन

ऑन-डिमांड सब्सक्रिप्शन से आप किसी customer के payment method को एक बार authorize कर सकते हैं और फिर fixed schedule के बजाय, आवश्यकता होने पर variable amounts charge कर सकते हैं। यह सुविधा सभी accounts के लिए उपलब्ध है—किसी approval की आवश्यकता नहीं है। इस गाइड का उपयोग इन कार्यों के लिए करें:
  • ऑन-डिमांड सब्सक्रिप्शन बनाएँ (optional initial price के साथ mandate authorize करें)
  • custom amounts के साथ subsequent charges trigger करें
  • webhooks का उपयोग करके outcomes track करें
सामान्य subscription setup के लिए Subscription Integration Guide देखें।

आवश्यकताएँ

  • Dodo Payments merchant account और API key
  • Webhook secret configured हो और events प्राप्त करने के लिए एक endpoint हो
  • आपके catalog में एक subscription product
यह गाइड checkout session (POST /checkouts) के माध्यम से ऑन-डिमांड सब्सक्रिप्शन बनाती है, जो हमेशा एक hosted checkout_url लौटाता है। Customer को mandate approve करने के लिए वहाँ redirect करें और return_url को उस स्थान पर set करें जहाँ customer को उसके बाद पहुँचना चाहिए।

ऑन-डिमांड कैसे काम करता है

  1. आप payment method को authorize करने और optional initial charge collect करने के लिए on_demand object के साथ subscription बनाते हैं।
  2. बाद में, dedicated charge endpoint का उपयोग करके उस subscription पर custom amounts के charges बनाते हैं।
  3. अपने system को update करने के लिए webhooks (जैसे payment.succeeded, payment.failed) सुनते हैं।

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

Endpoint: POST /checkouts मुख्य request fields (body):
इन्हें Create Checkout Session में देखें

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

Success

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

Mandate authorize होने के बाद, आवश्यकता के अनुसार charges बनाएँ। Endpoint: POST /subscriptions/{subscription_id}/charge मुख्य request fields (body):
integer
आवश्यक
Charge की जाने वाली राशि (currency की सबसे छोटी unit में)। उदाहरण: $25.00 charge करने के लिए 2500 pass करें।
string
Charge के लिए optional currency override।
string
इस charge के लिए optional description override।
boolean
यदि true है, तो product_price में Adaptive Currency fees शामिल होती हैं। यदि false है, तो fees अलग से जोड़ी जाती हैं।
object
Payment के लिए अतिरिक्त metadata। यदि इसे omit किया जाता है, तो subscription metadata का उपयोग होता है।
Success
ऐसी subscription पर charge करने पर जो on-demand नहीं है, failure हो सकता है। Charge करने से पहले सुनिश्चित करें कि subscription के details में on_demand: true मौजूद है।

Failed charges संभालना

जब on-demand subscription पर किया गया charge fail हो जाता है, तो आप तय करते हैं कि आगे क्या होगा। Scheduled subscriptions के विपरीत—जहाँ failed renewal के बाद automatic billing रुक जाती है—on-demand subscriptions failure के बाद भी chargeable रहती हैं। आप अपनी retry logic के हिस्से के रूप में charge endpoint को फिर call कर सकते हैं।

Failure होने पर क्या होता है

1

Charge attempt fails

POST /subscriptions/{subscription_id}/charge request या तो error response लौटाता है या asynchronously पूरा होकर decline reason के साथ payment.failed webhook emit करता है।
2

Subscription may transition to on_hold

Subscription on_hold state में जा सकती है और subscription.on_hold webhook emit कर सकती है (देखें Subscription States → On Hold)। यह एक signal है—lock नहीं। On-demand subscriptions के लिए, on_hold आपको दोबारा charge करने से नहीं रोकता
3

Retry the charge (your call)

On-demand flows में, Dodo अपने-आप retry नहीं करता। आप retry करने के लिए किसी भी समय POST /subscriptions/{subscription_id}/charge को फिर call कर सकते हैं। नीचे दी गई safe retry policy लागू करें—exponential backoff का उपयोग करें, hard declines को skip करें और burst patterns से बचें—ताकि हमारे fraud और risk systems retries को flag न करें।
4

Optionally, ask the customer for a new payment method

यदि payment method के खराब होने के कारण retries लगातार fail होती रहें (expired card, closed account आदि), तो customer से नया payment method collect करने के लिए POST /subscriptions/{subscription_id}/update-payment-method का उपयोग करें। सफलता मिलने पर subscription active पर लौटती है और payment.succeeded के बाद subscription.active webhooks emit होते हैं।
On-demand बनाम scheduled: Scheduled subscriptions के लिए, Dodo अपने renewal retries और dunning चलाता है। On-demand subscriptions के लिए retry policy आपकी जिम्मेदारी है, क्योंकि केवल आप जानते हैं कि अगला charge कब होना चाहिए (यह calendar के बजाय आपके usage events से निर्धारित होता है)।

Failed on-demand charge पर webhook sequence

Events 3 और 4 केवल follow-up charge सफल होने के बाद fire होते हैं।

Retry की जिम्मेदारी

Dodo Payments failed on-demand charges को auto-retry नहीं करता। Retry policy आपकी जिम्मेदारी है। Card testing के रूप में हमारे fraud detection systems द्वारा flag किए जाने से बचने के लिए नीचे दिए गए safe retry guidelines का पालन करें।
Subscription Dunning—built-in email recovery sequence—scheduled subscriptions पर failed renewal payments और customer-initiated cancellations तक सीमित है। इसे on-demand charge failures के लिए design नहीं किया गया है। जब आपको लगे कि payment method update करने की आवश्यकता है, तो customer से सीधे (जैसे transactional email या in-app prompt के माध्यम से) संपर्क करें।

Payment retries

हमारा fraud detection system aggressive retry patterns को block कर सकता है और उन्हें संभावित card testing के रूप में flag कर सकता है। Safe retry policy का पालन करें।
Burst retry patterns को हमारे risk systems और processors fraudulent या suspected card testing के रूप में flag कर सकते हैं। Clustered retries से बचें; नीचे दिए गए backoff schedule और time-alignment guidance का पालन करें।

Safe retry policies के सिद्धांत

  • Backoff mechanism: Retries के बीच exponential backoff का उपयोग करें।
  • Retry limits: कुल retries की सीमा तय करें (अधिकतम 3–4 attempts)।
  • Intelligent filtering: केवल retryable failures (जैसे network/issuer errors, insufficient funds) पर retry करें; hard declines पर कभी retry न करें।
  • Card testing prevention: DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE जैसी failures पर retry न करें।
  • Metadata बदलें (optional): यदि आप अपना retry system maintain करते हैं, तो metadata के माध्यम से retries को अलग पहचान दें (जैसे retry_attempt)।

सुझाया गया retry schedule (subscriptions)

  • 1st attempt: Charge बनाते समय तुरंत
  • 2nd attempt: 3 दिनों के बाद
  • 3rd attempt: 7 और दिनों के बाद (कुल 10 दिन)
  • 4th attempt (final): अगले 7 दिनों के बाद (कुल 17 दिन)
अंतिम चरण: यदि payment अब भी unpaid है, तो अपनी policy के आधार पर subscription को unpaid mark करें या cancel करें। Customer को payment method update करने के लिए इस अवधि के दौरान सूचित करें।

Burst retries से बचें; authorization time के अनुसार align करें

  • अपने portfolio में “burst” behavior से बचने के लिए retries को original authorization timestamp से anchor करें।
  • उदाहरण: यदि customer आज 1:10 pm पर trial या mandate शुरू करता है, तो अपनी backoff के अनुसार subsequent days में 1:10 pm पर follow-up retries schedule करें (जैसे, +3 days → 1:10 pm, +7 days → 1:10 pm)।
  • वैकल्पिक रूप से, यदि आप last successful payment time T store करते हैं, तो time-of-day alignment बनाए रखने के लिए अगला attempt T + X days पर schedule करें।
Time-zone और DST: scheduling के लिए consistent time standard का उपयोग करें और intervals बनाए रखने के लिए केवल display हेतु convert करें।

वे decline codes जिन पर retry नहीं करना चाहिए

  • STOLEN_CARD
  • DO_NOT_HONOR
  • FRAUDULENT
  • PICKUP_CARD
  • AUTHENTICATION_FAILURE
  • LOST_CARD
Decline reasons की पूरी सूची और यह जानने के लिए कि उन्हें user ठीक कर सकता है या नहीं, Transaction Failures documentation देखें।
केवल soft/temporary issues (जैसे insufficient_funds, issuer_unavailable, processing_error, network timeouts) पर retry करें। यदि वही decline दोबारा होता है, तो आगे के retries रोक दें।

Implementation guidelines (no code)

  • ऐसे scheduler/queue का उपयोग करें जो precise timestamps persist करे; next attempt को exact time-of-day offset पर compute करें (जैसे T + 3 days उसी HH:MM पर)।
  • Next attempt compute करने के लिए last successful payment timestamp T को maintain और reference करें; कई subscriptions को एक ही instant पर bunch न करें।
  • Last decline reason का हमेशा evaluation करें; ऊपर दी गई skip list में मौजूद hard declines पर retries रोक दें।
  • Accidental surges रोकने के लिए प्रति customer और प्रति account concurrent retries की सीमा तय करें।
  • Proactively communicate करें: अगले scheduled attempt से पहले customer को payment method update करने के लिए email/SMS भेजें।
  • Metadata का उपयोग केवल observability के लिए करें (जैसे retry_attempt); inconsequential fields rotate करके fraud/risk systems को “evade” करने का प्रयास कभी न करें।

Cancellation

On-demand subscriptions का cancellation flow scheduled subscriptions से अलग होता है, क्योंकि immediate end date को anchor करने के लिए कोई fixed billing cycle नहीं होता।

Customer Portal का व्यवहार

जब कोई customer Customer Portal से on-demand subscription cancel करता है, तो cancellation default रूप से next billing date के लिए schedule होती है। On-demand subscriptions के लिए Cancel Now option जानबूझकर नहीं दिखाया जाता। कारण यह है कि on-demand subscriptions में predictable recurring renewal dates नहीं होतीं—अगले charge का समय पूरी तरह आपके usage events से निर्धारित होता है। Next billing date पर cancellation schedule करने से period boundary तक mandate active रहता है, इसलिए in-flight usage अभी भी charge किया जा सकता है और उसके बाद subscription ठीक से समाप्त होती है। Customer द्वारा cancellation confirm करने के बाद:
  • Subscription active रहती है और scheduled cancellation date तक POST /subscriptions/{id}/charge के माध्यम से chargeable रहती है।
  • Subscription पर cancel_at_next_billing_date को true पर set किया जाता है।
  • Cancellation प्रभावी होने पर subscription.cancelled webhook emit होता है।
यदि आपको subscription तुरंत समाप्त करनी हो (उदाहरण के लिए refund या support request के जवाब में), तो Customer Portal flow पर निर्भर रहने के बजाय API के माध्यम से इसे programmatically cancel करें।

Programmatically cancel करें

आप API के माध्यम से किसी भी समय on-demand subscription cancel कर सकते हैं। Cancellation immediate होगी या scheduled, यह आप नियंत्रित करते हैं। Endpoint: PATCH /subscriptions/{subscription_id}
Subscription को तुरंत समाप्त करने के लिए उसका status, cancelled पर set करें। Mandate revoke हो जाता है और आगे कोई charge create नहीं किया जा सकता।
cURL

Cancellation पर webhooks

अपने handler में on-demand cancellations को scheduled-subscription cancellations से अलग पहचानने के लिए webhook process करते समय subscription का on_demand flag check करें।

Webhooks के साथ outcomes track करें

Customer journey track करने के लिए webhook handling implement करें। Implementing Webhooks देखें।
  • subscription.active: Mandate authorize हुआ और subscription activate हुई
  • subscription.failed: Creation fail हुई (जैसे mandate failure)
  • subscription.on_hold: Subscription hold पर रखी गई (जैसे unpaid state)
  • subscription.cancelled: Subscription पूरी तरह cancel हुई (देखें Cancellation)
  • payment.succeeded: Charge सफल हुआ
  • payment.failed: Charge fail हुआ
On-demand flows के लिए usage-based charges reconcile करने हेतु payment.succeeded और payment.failed पर ध्यान दें। जब payment.failed के बाद subscription.on_hold आए, तो subscription recover करने के लिए Handling failed charges देखें।

Testing और अगले चरण

1

Create in test mode

Subscription बनाने के लिए अपनी test API key का उपयोग करें, फिर लौटाए गए checkout_url को खोलकर mandate पूरा करें।
2

Trigger a charge

छोटी product_price (जैसे 100) के साथ charge endpoint call करें और verify करें कि आपको payment.succeeded प्राप्त हुआ है।
3

Go live

Events और internal state updates validate करने के बाद अपनी live API key पर switch करें।

Troubleshooting

  • 422 Invalid Request: सुनिश्चित करें कि creation के समय on_demand.mandate_only और charges के लिए product_price प्रदान किया गया है।
  • Currency errors: यदि आप product_currency override करते हैं, तो पुष्टि करें कि यह आपके account और customer के लिए supported है।
  • No webhooks received: अपने webhook URL और signature secret configuration को verify करें।
अंतिम संशोधन 31 जुलाई 2026