Ö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_demandobjektet för att auktorisera en betalningsmetod och eventuellt samla in en initial avgift. - Senare skapar du avgifter mot den prenumerationen med anpassade belopp via den dedikerade avgifts-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):Parametrar för avgiftsbegäran
Parametrar för avgiftsbegäran
Belopp att ta ut (i den minsta valutaenheten). Exempel: för att ta ut $25.00, skicka
2500.Valfritt valutauppdrag för avgiften.
Valfritt beskrivningsuppdrag för denna avgift.
Om sant, inkluderar adaptiva valutavgifter inom
product_price. Om falskt, läggs avgifterna till ovanpå.Ytterligare metadata för betalningen. Om utelämnat, används prenumerationsmetadata.
- 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
- Nedtrappningsmekanism: Använd exponentiell nedtrappning mellan återförsök.
- Återförsöksgränser: Sätt en gräns för totala återförsök (3–4 försök max).
- Intelligent filtrering: Återförsök endast vid återförbara fel (t.ex. nätverks-/utfärdarfel, otillräckliga medel); återförsök aldrig vid hårda avslag.
- Förhindra korttestning: Återförsök inte vid avslag som
DO_NOT_HONOR,STOLEN_CARD,LOST_CARD,PICKUP_CARD,FRAUDULENT,AUTHENTICATION_FAILURE. - Variera metadata (valfritt): Om du upprätthåller ditt eget återförsökssystem, differentiera återförsök 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
- Ankra återförsök till den ursprungliga auktoriseringstidsstämpeln för att undvika “burst”-beteende över din portfölj.
- Exempel: Om kunden startar en provperiod eller mandat klockan 13:10 idag, schemalägg uppföljande återförsök klockan 13:10 på följande dagar enligt din nedtrappning (t.ex. +3 dagar → 13:10, +7 dagar → 13:10).
- Alternativt, om du lagrar den senaste framgångsrika betalningstiden
T, schemalägg nästa försök vidT + X daysför att bevara tidsjusteringen.
Tidszon och DST: använd en konsekvent tidsstandard för schemaläggning och konvertera endast för visning för att upprätthålla intervall.
Avslagkoder du inte bör återförsöka
STOLEN_CARDDO_NOT_HONORFRAUDULENTPICKUP_CARDAUTHENTICATION_FAILURELOST_CARD
För en omfattande lista över avslagsskäl och huruvida de kan rättas av användaren, se dokumentationen för
Transaktionsfel.
Implementeringsriktlinjer (ingen kod)
- Använd en schemaläggare/kö som bevarar exakta tidsstämplar; beräkna nästa försök vid exakt tidpunkt (t.ex.
T + 3 daysvid samma HH:MM). - Upprätthåll och referera till den senaste framgångsrika betalningstidsstämpeln
Tför att beräkna nästa försök; gruppera aldrig flera prenumerationer vid samma tillfälle. - Utvärdera alltid den senaste avslagsskäl; stoppa återförsök för hårda avslag i den ovanstående hoppa-listan.
- Sätt en gräns för samtidiga återförsök per kund och per konto för att förhindra oavsiktliga toppar.
- Kommunicera proaktivt: e-posta/SMS:a kunden för att uppdatera sin betalningsmetod innan nästa schemalagda försök.
- Använd metadata endast för observabilitet (t.ex.
retry_attempt); försök aldrig att “undvika” bedrägeri/risk-system genom att rotera oväsentliga 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
Skapa i testläge
Använd din test-API-nyckel för att skapa prenumerationen med
payment_link: true, öppna sedan länken och slutför mandatet.Utlösa en avgift
Anropa avgifts-slutpunkten med en liten
product_price (t.ex. 100) och verifiera att du får payment.succeeded.Felsökning
- 422 Ogiltig begäran: Se till att
on_demand.mandate_onlytillhandahålls vid skapande ochproduct_pricetillhandahålls för avgifter. - Valuta fel: Om du åsidosätter
product_currency, bekräfta att den stöds för ditt konto och kund. - Inga webhooks mottagna: Verifiera din webhook-URL och signaturhemlighetskonfiguration.