On-Demand Prenumerationer

Ö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. Använd denna guide för att:

Skapa en on-demand prenumeration (auktorisera ett mandat med valfritt initialt pris)
Utlösa efterföljande avgifter med anpassade belopp
Spåra resultat med hjälp av webhooks

För en allmän prenumerationsinställning, se Prenumerationsintegrationsguide.

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 hostad kassa, ställ in payment_link: true och tillhandahåll en return_url.

Hur on-demand fungerar

Du skapar en prenumeration med on_demand objektet 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 avgiftsslutpunkten.
Du lyssnar på webhooks (t.ex. payment.succeeded, payment.failed) för att uppdatera ditt system.

Skapa en on-demand prenumeration

Slutpunkt: POST /subscriptions Nyckelfält i begäran (kropp):

Begäran Kropp Parametrar

product_id

string

obligatorisk

Produkt-ID för prenumerationen.

quantity

integer

obligatorisk

Antal enheter. Minst 1.

billing

object

obligatorisk

Faktureringsadress för kunden.

customer

object

obligatorisk

Antingen koppla en befintlig kund eller tillhandahålla kundinformation.

payment_link

boolean

standard:"false"

Om sant, skapar en hostad kassa-länk för mandatauktorisering och valfri initial betalning.

return_url

string

Var kunden ska omdirigeras efter att ha slutfört den hostade kassan.

on_demand.mandate_only

boolean

obligatorisk

Om sant, auktoriserar betalningsmetoden utan att ta ut avgift från kunden vid skapandet.

on_demand.product_price

integer

Initial avgiftsbelopp (i den minsta valutanheten). Om angivet, åsidosätter detta värde produktens ursprungliga pris som ställts in vid produktens skapande. Om utelämnat, används produktens lagrade pris. Exempel: för att ta ut $1.00, skicka 100.

on_demand.product_currency

string

Valfritt valöverskridande för den initiala avgiften. Standardinställning är produktens valuta.

on_demand.product_description

string

Valfritt beskrivningsöverskridande för fakturering och linjeposter.

on_demand.adaptive_currency_fees_inclusive

boolean

Om sant, inkluderar adaptiva valutavgifter inom product_price. Om falskt, läggs avgifterna till ovanpå. Ignoreras när adaptiv prissättning är inaktiverad.

Skapa en on-demand prenumeration

Node.js SDK
Python SDK
Go SDK
cURL

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.subscriptions.create({
    billing: { city: 'SF', country: 'US', state: 'CA', street: '1 Market St', zipcode: '94105' },
    customer: { customer_id: 'customer_123' },
    product_id: 'prod_sub_123',
    quantity: 1,
    payment_link: true,
    return_url: 'https://example.com/billing/success',
    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,
    },
  });

  // If payment_link was true, redirect the customer to authorize the mandate
  console.log(subscription.payment_link);
}

main().catch(console.error);

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get('DODO_PAYMENTS_API_KEY'),
    environment="test_mode",  # defaults to "live_mode"
)

subscription = client.subscriptions.create(
    billing={
        "city": "SF",
        "country": "US",
        "state": "CA",
        "street": "1 Market St",
        "zipcode": "94105",
    },
    customer={"customer_id": "customer_123"},
    product_id="prod_sub_123",
    quantity=1,
    payment_link=True,
    return_url="https://example.com/billing/success",
    on_demand={
        "mandate_only": True,
        # "product_price": 1000,
        # "product_currency": "USD",
        # "product_description": "Custom initial charge",
        # "adaptive_currency_fees_inclusive": False,
    },
)

print(subscription.payment_link)

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(
    option.WithBearerToken("YOUR_API_KEY"),
  )
  subscription, err := client.Subscriptions.New(context.TODO(), dodopayments.SubscriptionNewParams{
    Billing: dodopayments.F(dodopayments.BillingAddressParam{
      City:    dodopayments.F("SF"),
      Country: dodopayments.F(dodopayments.CountryCodeUs),
      State:   dodopayments.F("CA"),
      Street:  dodopayments.F("1 Market St"),
      Zipcode: dodopayments.F("94105"),
    }),
    Customer: dodopayments.F[dodopayments.CustomerRequestUnionParam](dodopayments.AttachExistingCustomerParam{
      CustomerID: dodopayments.F("customer_123"),
    }),
    ProductID:  dodopayments.F("prod_sub_123"),
    Quantity:   dodopayments.F(int64(1)),
    PaymentLink: dodopayments.F(true),
    ReturnURL:   dodopayments.F("https://example.com/billing/success"),
    OnDemand: dodopayments.F(dodopayments.OnDemandSubscriptionReqParam{
      MandateOnly: dodopayments.F(true),
      // ProductPrice: dodopayments.F(int64(1000)),
      // ProductCurrency: dodopayments.F(dodopayments.CurrencyUsd),
      // ProductDescription: dodopayments.F("Custom initial charge"),
      // AdaptiveCurrencyFeesInclusive: dodopayments.F(false),
    }),
  })
  if err != nil { panic(err) }
  fmt.Println(subscription.PaymentLink)
}

curl -X POST "$DODO_API/subscriptions" \
  -H "Authorization: Bearer $DODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "billing": {"city": "SF", "country": "US", "state": "CA", "street": "1 Market St", "zipcode": "94105"},
    "customer": {"customer_id": "customer_123"},
    "product_id": "prod_sub_123",
    "quantity": 1,
    "payment_link": true,
    "return_url": "https://example.com/billing/success",
    "on_demand": {
      "mandate_only": true
    }
  }'

Ställ in payment_link: true, omdirigera kunden till payment_link för att slutföra mandatauktoriseringen.

Success

{
  "subscription_id": "sub_123",
  "payment_link": "https://pay.dodopayments.com/checkout/...",
  "customer": { "customer_id": "customer_123", "email": "[email protected]", "name": "Alex Doe" },
  "metadata": {},
  "recurring_pre_tax_amount": 0,
  "addons": []
}

Ta ut en on-demand prenumeration

Efter att mandatet har auktoriserats, skapa avgifter vid behov. Slutpunkt: POST /subscriptions/{subscription_id}/charge Nyckelfält i begäran (kropp):

Avgiftsbegäran kropp parametrar

product_price

integer

obligatorisk

Belopp att ta ut (i den minsta valutanheten). Exempel: för att ta ut $25.00, skicka 2500.

product_currency

string

Valfritt valöverskridande för avgiften.

product_description

string

Valfritt beskrivningsöverskridande 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 prenumerationens metadata.

Node.js SDK
Python SDK
Go SDK
cURL

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

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);

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get('DODO_PAYMENTS_API_KEY'),
    environment="test_mode",  # defaults to "live_mode"
)

response = client.subscriptions.charge(
    subscription_id="sub_123",
    product_price=2500,
)

print(response.payment_id)

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(option.WithBearerToken("YOUR_API_KEY"))
  res, err := client.Subscriptions.Charge(context.TODO(), "sub_123", dodopayments.SubscriptionChargeParams{
    ProductPrice: dodopayments.F(int64(2500)),
  })
  if err != nil { panic(err) }
  fmt.Println(res.PaymentID)
}

curl -X POST "$DODO_API/subscriptions/sub_123/charge" \
  -H "Authorization: Bearer $DODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_price": 2500,
    "product_description": "Extra usage for March"
  }'

Success

{ "payment_id": "pay_abc123" }

Att ta ut 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öringar

Vårt bedrägeridetekteringssystem kan blockera aggressiva återföringsmönster (och kan flagga dem som potentiell korttestning). Följ en säker återföringspolicy.

Burst-återföringsmönster kan flaggas som bedrägliga eller misstänkta korttester av våra risk- och processor-system. Undvik klusteråterföringar; följ nedan angiven backoff-schema och tidsjusteringsriktlinjer.

Principer för säkra återföringspolicyer

Backoff-mekanism: Använd exponentiell backoff mellan återföringar.
Återföringsgränser: Sätt ett tak för totala återföringar (3–4 försök max).
Intelligent filtrering: Återför endast vid återföringsbara fel (t.ex. nätverks-/utfärdarfel, otillräckliga medel); återför aldrig hårda avslag.
Förhindra korttestning: Återför inte fel som DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
Variera metadata (valfritt): Om du upprätthåller ditt eget återföringssystem, särskilj återföringar via metadata (t.ex. retry_attempt).

Föreslagen återföringsschema (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öringar; justera till auktoriseringstid

Ankare återföringar 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öringar klockan 13:10 på följande dagar enligt din backoff (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 sommartid: använd en konsekvent tidsstandard för schemaläggning och konvertera endast för visning för att upprätthålla intervall.

Avslag koder du inte bör återföras

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ör endast vid mjuka/temporära problem (t.ex. insufficient_funds, issuer_unavailable, processing_error, nätverksavbrott). Om samma avslag upprepas, pausa ytterligare återföringar.

Implementeringsriktlinjer (ingen kod)

Använd en schemaläggare/kö som bevarar exakta tidsstämplar; beräkna nästa försök vid exakt tid-of-day-offset (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 ögonblick.
Utvärdera alltid den senaste avslagsskäl; stoppa återföringar för hårda avslag i ovanstående hoppa-lista.
Sätt ett tak för samtidiga återföringar 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. mandatfel)
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

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.

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.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Översikt

Förutsättningar

Hur on-demand fungerar

Skapa en on-demand prenumeration

Skapa en on-demand prenumeration

Ta ut en on-demand prenumeration

Betalningsåterföringar

Principer för säkra återföringspolicyer

Föreslagen återföringsschema (prenumerationer)

Undvik burst-återföringar; justera till auktoriseringstid

Avslag koder du inte bör återföras

Implementeringsriktlinjer (ingen kod)

Spåra resultat med webhooks

Testning och nästa steg

Felsökning

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

​Översikt

​Förutsättningar

​Hur on-demand fungerar

​Skapa en on-demand prenumeration

​Skapa en on-demand prenumeration

​Ta ut en on-demand prenumeration

​Betalningsåterföringar

​Principer för säkra återföringspolicyer

​Föreslagen återföringsschema (prenumerationer)

​Undvik burst-återföringar; justera till auktoriseringstid

​Avslag koder du inte bör återföras

​Implementeringsriktlinjer (ingen kod)

​Spåra resultat med webhooks

​Testning och nästa steg

​Felsökning

Översikt

Förutsättningar

Hur on-demand fungerar

Skapa en on-demand prenumeration

Skapa en on-demand prenumeration

Ta ut en on-demand prenumeration

Betalningsåterföringar

Principer för säkra återföringspolicyer

Föreslagen återföringsschema (prenumerationer)

Undvik burst-återföringar; justera till auktoriseringstid

Avslag koder du inte bör återföras

Implementeringsriktlinjer (ingen kod)

Spåra resultat med webhooks

Testning och nästa steg

Felsökning