Översikt
On-demand-prenumerationer låter dig auktorisera en kunds betalningsmetod en gång och sedan ta ut variabla belopp när du behöver, istället för på ett fast schema. Denna funktion är tillgänglig för alla konton—ingen godkännande krävs. Använd denna guide för att:- Skapa en on-demand-prenumeration (auktorisera ett mandat med valfritt initialpris)
- Utlösa efterföljande avgifter med anpassade belopp
- Spåra resultat med hjälp av webhooks
Förutsättningar
- Dodo Payments handelskonto och API-nyckel
- Webhook-hemlighet konfigurerad och en slutpunkt för att ta emot händelser
- En prenumerationsprodukt i din katalog
Hur on-demand fungerar
- Du skapar en prenumeration med
on_demand-objektet för att auktorisera en betalningsmetod och eventuellt ta ut en första avgift. - Senare skapar du avgifter mot den prenumerationen med anpassade belopp via den dedikerade charge-slutpunkten.
- Du lyssnar på webhooks (t.ex.
payment.succeeded,payment.failed) för att uppdatera ditt system.
Skapa en on-demand-prenumeration
Slutpunkt: POST /checkouts Nyckelfält för begäran (kropp):Vänligen se dem i Skapa Checkout-session
Skapa en on-demand-prenumeration
- Node.js SDK
- Python SDK
- Go SDK
- cURL
Success
Ta ut en avgift för en on-demand-prenumeration
Efter att mandatet har auktoriserats, skapa avgifter vid behov. Slutpunkt: POST /subscriptions/{subscription_id}/charge Nyckelfält för begäran (kropp):Charge request body parameters
Charge request body parameters
Belopp att debitera (i den minsta valutabeteckningen). Exempel: för att debitera $25,00, skicka
2500.Valfri valutaoch överstyrning för avgiften.
Valfri beskrivningsöverstyrning för denna avgift.
Om sant, inkluderas adaptiva valutavgifter i
product_price. Om falskt läggs avgifterna ovanpå.Ytterligare metadata för betalningen. Om det utelämnas används prenumerationens metadata.
- Node.js SDK
- Python SDK
- Go SDK
- cURL
Success
Betalningsåterförsök
Vårt bedrägeridetekteringssystem kan blockera aggressiva återförsöksmönster (och kan flagga dem som potentiell korttestning). Följ en säker återförsökspolicy.Principer för säkra återförsökspolicys
- Backoff-mekanism: Använd exponentiell backoff mellan försök.
- Retrysgränser: Begränsa totala försök (3–4 försök max).
- Intelligent filtrering: Försök bara igen vid omförsökbara fel (t.ex. nätverks-/utfärdarfel, otillräckliga medel); försök aldrig igen vid ett fast avslag.
- Förebygg korttestning: Försök inte igen vid fel som
DO_NOT_HONOR,STOLEN_CARD,LOST_CARD,PICKUP_CARD,FRAUDULENT,AUTHENTICATION_FAILURE. - Variera metadata (valfritt): Om du har ett eget retry-system, särskilj retry-tillfällen via metadata (t.ex.
retry_attempt).
Föreslaget återförsökschema (prenumerationer)
- 1:a försök: Omedelbart när du skapar avgiften
- 2:a försök: Efter 3 dagar
- 3:e försök: Efter ytterligare 7 dagar (10 dagar totalt)
- 4:e försök (slutgiltigt): Efter ytterligare 7 dagar (17 dagar totalt)
Undvik burst-återförsök; anpassa till auktoriseringstid
- Anslut omförsök till ursprunglig auktoriseringstidpunkt för att undvika “burst”-beteende över din portfölj.
- Exempel: Om kunden startar en testperiod eller mandat kl. 13:10 idag, schemalägg följande omförsök kl. 13:10 på efterföljande dagar enligt din backoff (t.ex. +3 dagar → 13:10, +7 dagar → 13:10).
- Alternativt, om du sparar den senaste lyckade betalningstiden
T, planera nästa försök vidT + X daysför att bevara tidpunkten.
Tidszon och sommartid: använd en konsekvent tidsstandard för schemaläggning och konvertera endast för visning för att behålla intervallen.
Avslagkoder du inte bör återförsöka
STOLEN_CARDDO_NOT_HONORFRAUDULENTPICKUP_CARDAUTHENTICATION_FAILURELOST_CARD
För en komplett lista över avvisningsorsaker och huruvida de kan rättas av användaren, se dokumentationen
Transaction Failures.
Implementeringsriktlinjer (ingen kod)
- Använd en schemaläggare/kö som sparar exakta tidsstämplar; beräkna nästa försök vid exakt samma tidpunkt (t.ex.
T + 3 daysvid samma HH:MM). - Behåll och referera till den senaste lyckade betalningstidsstämpeln
Tför att beräkna nästa försök; samla inte flera prenumerationer vid samma ögonblick. - Utvärdera alltid den senaste avvisningsorsaken; stoppa omförsök för fasta avslag i listan ovan.
- Begränsa samtidiga omförsök per kund och per konto för att förhindra oavsiktliga toppar.
- Kommunicera proaktivt: skicka e-post/SMS till kunden för att uppdatera deras betalningsmetod före nästa planerade försök.
- Använd metadata endast för observabilitet (t.ex.
retry_attempt); försök aldrig “undkomma” bedrägeri-/riskssystem genom att rotera obetydliga fält.
Spåra resultat med webhooks
Implementera webhook-hantering för att spåra kundresan. Se Implementera Webhooks.- subscription.active: Mandat auktoriserat och prenumeration aktiverad
- subscription.failed: Skapande misslyckades (t.ex. mandatmisslyckande)
- subscription.on_hold: Prenumeration placerad på håll (t.ex. obetald status)
- payment.succeeded: Avgift lyckades
- payment.failed: Avgift misslyckades
Testning och nästa steg
Create in test mode
Använd din test-API-nyckel för att skapa prenumerationen med
payment_link: true, öppna länken och slutför mandatet.Trigger a charge
Anropa charge-slutpunkten med ett litet
product_price (t.ex. 100) och verifiera att du får payment.succeeded.Felsökning
- 422 Ogiltig förfrågan: Säkerställ att
on_demand.mandate_onlytillhandahålls vid skapande och attproduct_pricetillhandahålls för avgifter. - Valutafel: Om du åsidosätter
product_currency, bekräfta att den stöds för ditt konto och din kund. - Inga webhooks mottagna: Verifiera din webhook-URL och signaturhemlighetskonfiguration.