अवलोकन
ऑन-डिमांड सब्सक्रिप्शन से आप किसी customer के payment method को एक बार authorize कर सकते हैं और फिर fixed schedule के बजाय, आवश्यकता होने पर variable amounts charge कर सकते हैं। यह सुविधा सभी accounts के लिए उपलब्ध है—किसी approval की आवश्यकता नहीं है। इस गाइड का उपयोग इन कार्यों के लिए करें:- ऑन-डिमांड सब्सक्रिप्शन बनाएँ (optional initial price के साथ mandate authorize करें)
- custom amounts के साथ subsequent charges trigger करें
- webhooks का उपयोग करके outcomes track करें
आवश्यकताएँ
- Dodo Payments merchant account और API key
- Webhook secret configured हो और events प्राप्त करने के लिए एक endpoint हो
- आपके catalog में एक subscription product
ऑन-डिमांड कैसे काम करता है
- आप payment method को authorize करने और optional initial charge collect करने के लिए
on_demandobject के साथ subscription बनाते हैं। - बाद में, dedicated charge endpoint का उपयोग करके उस subscription पर custom amounts के charges बनाते हैं।
- अपने system को update करने के लिए webhooks (जैसे
payment.succeeded,payment.failed) सुनते हैं।
ऑन-डिमांड सब्सक्रिप्शन बनाएँ
Endpoint: POST /checkouts मुख्य request fields (body):इन्हें Create Checkout Session में देखें
ऑन-डिमांड सब्सक्रिप्शन बनाएँ
- Node.js SDK
- Python SDK
- Go SDK
- cURL
Success
ऑन-डिमांड सब्सक्रिप्शन पर charge करें
Mandate authorize होने के बाद, आवश्यकता के अनुसार charges बनाएँ। Endpoint: POST /subscriptions/{subscription_id}/charge मुख्य request fields (body):Charge request body parameters
Charge request body parameters
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 का उपयोग होता है।
- Node.js SDK
- Python SDK
- Go SDK
- cURL
Success
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 की जिम्मेदारी
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 का पालन करें।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 दिन)
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
Tstore करते हैं, तो time-of-day alignment बनाए रखने के लिए अगला attemptT + X daysपर schedule करें।
Time-zone और DST: scheduling के लिए consistent time standard का उपयोग करें और intervals बनाए रखने के लिए केवल display हेतु convert करें।
वे decline codes जिन पर retry नहीं करना चाहिए
STOLEN_CARDDO_NOT_HONORFRAUDULENTPICKUP_CARDAUTHENTICATION_FAILURELOST_CARD
Decline reasons की पूरी सूची और यह जानने के लिए कि उन्हें user ठीक कर सकता है या नहीं, Transaction Failures documentation देखें।
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.cancelledwebhook 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}- Cancel immediately
- Cancel at next billing date
Subscription को तुरंत समाप्त करने के लिए उसका
status, cancelled पर set करें। Mandate revoke हो जाता है और आगे कोई charge create नहीं किया जा सकता।cURL
Cancellation पर webhooks
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 हुआ
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_currencyoverride करते हैं, तो पुष्टि करें कि यह आपके account और customer के लिए supported है। - No webhooks received: अपने webhook URL और signature secret configuration को verify करें।