Hoppa till huvudinnehåll

Ö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ör en allmän prenumerationsinställning, se Prenumerationsintegrationsguiden.

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
Om du vill att kunden ska godkänna mandatet via en värd-checkout, ställ in payment_link: true och tillhandahåll en return_url.

Hur on-demand fungerar

  1. Du skapar en prenumeration med on_demand objektet för att auktorisera en betalningsmetod och eventuellt samla in en initial avgift.
  2. Senare skapar du avgifter mot den prenumerationen med anpassade belopp via den dedikerade avgifts-slutpunkten.
  3. 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

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 subscription = await client.checkoutSessions.create({
    product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
    billing_address:  { city: 'SF', country: 'US', state: 'CA', street: '1 Market St', zipcode: '94105' },
    customer: { customer_id: 'cus_123' },
    return_url: 'https://example.com/billing/success',
    subscription_data: {
        on_demand: {
            mandate_only: true // set false to collect an initial charge
            // product_price: 1000, // optional: charge $10.00 now if mandate_only is false
            // product_currency: 'USD',
            // product_description: 'Custom initial charge',
            // adaptive_currency_fees_inclusive: false,
        }
    }
  });

  console.log(subscription.checkout_url);
}

main().catch(console.error);
Success
{
  "session_id": "cks_123",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks123"
}

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):
product_price
integer
obligatorisk
Belopp att ta ut (i den minsta valutaenheten). Exempel: för att ta ut $25.00, skicka 2500.
product_currency
string
Valfritt valutauppdrag för avgiften.
product_description
string
Valfritt beskrivningsuppdrag för denna avgift.
adaptive_currency_fees_inclusive
boolean
Om sant, inkluderar adaptiva valutavgifter inom product_price. Om falskt, läggs avgifterna till ovanpå.
metadata
object
Ytterligare metadata för betalningen. Om utelämnat, används prenumerationsmetadata.
import DodoPayments from 'dodopayments';

const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY });

async function chargeNow(subscriptionId) {
  const res = await client.subscriptions.charge(subscriptionId, { product_price: 2500 });
  console.log(res.payment_id);
}

chargeNow('sub_123').catch(console.error);
Success
{ "payment_id": "pay_abc123" }
Att ta ut en avgift för en prenumeration som inte är on-demand kan misslyckas. Se till att prenumerationen har on_demand: true i sina detaljer innan du tar ut avgiften.

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.
Burst-återförsöksmönster kan flaggas som bedrägliga eller misstänkt korttestning av våra risk- och processor-system. Undvik klusteråterförsök; följ nedtrappningsschemat och tidsjusteringsguiden nedan.

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)
Slutsteg: om fortfarande obetald, markera prenumerationen som obetald eller avbryt den, baserat på din policy. Meddela kunden under fönstret för att uppdatera sin betalningsmetod.

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 vid T + X days fö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_CARD
  • DO_NOT_HONOR
  • FRAUDULENT
  • PICKUP_CARD
  • AUTHENTICATION_FAILURE
  • LOST_CARD
För en omfattande lista över avslagsskäl och huruvida de kan rättas av användaren, se dokumentationen för Transaktionsfel.
Återförsök endast vid mjuka/temporära problem (t.ex. insufficient_funds, issuer_unavailable, processing_error, nätverksavbrott). Om samma avslag upprepas, pausa ytterligare återförsök.

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 days vid samma HH:MM).
  • Upprätthåll och referera till den senaste framgångsrika betalningstidsstämpeln T fö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
För on-demand-flöden, fokusera på payment.succeeded och payment.failed för att avstämma användningsbaserade avgifter.

Testning och nästa steg

1

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.
2

Utlösa en avgift

Anropa avgifts-slutpunkten med en liten product_price (t.ex. 100) och verifiera att du får payment.succeeded.
3

Gå live

Byt till din live API-nyckel när du har validerat händelser och interna tillståndsuppdateringar.

Felsökning

  • 422 Ogiltig begäran: Se till att on_demand.mandate_only tillhandahålls vid skapande och product_price tillhandahå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.