Integrationsguide för prenumerationer

​

Förutsättningar

• Ett handlarkonto hos Dodo Payments
• En API-nyckel från Developer → API Keys i kontrollpanelen, lagrad i DODO_PAYMENTS_API_KEY
• En webhook-hemlighet från Developer → Webhooks, lagrad i DODO_PAYMENTS_WEBHOOK_KEY
• Minst en prenumerationsprodukt skapad under Products

​

API-integrering

​

Checkout-sessioner

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 session = await client.checkoutSessions.create({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    // Optional: configure trials for subscription products
    subscription_data: { trial_period_days: 14 },
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe',
    },
    return_url: 'https://example.com/success',
  });

  console.log(session.checkout_url);
}

main();

import os
from dodopayments import DodoPayments

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

session = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "pdt_subscription_monthly", "quantity": 1}
    ],
    subscription_data={"trial_period_days": 14},  # optional
    customer={
        "email": "subscriber@example.com",
        "name": "Jane Doe",
    },
    return_url="https://example.com/success",
)

print(session.checkout_url)

const response = await fetch('https://test.dodopayments.com/checkouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.DODO_PAYMENTS_API_KEY}`
  },
  body: JSON.stringify({
    product_cart: [
      { product_id: 'pdt_subscription_monthly', quantity: 1 }
    ],
    subscription_data: { trial_period_days: 14 }, // optional
    customer: {
      email: 'subscriber@example.com',
      name: 'Jane Doe'
    },
    return_url: 'https://example.com/success'
  })
});

if (!response.ok) {
  throw new Error(`HTTP error! status: ${response.status}`);
}

const session = await response.json();
console.log(session.checkout_url);

​

API-svar

{
  "session_id": "cks_Gi6KGJ2zFJo9rq9Ukifwa",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks_Gi6KGJ2zFJo9rq9Ukifwa"
}

​

Webhooks

​

Typer av prenumerationshändelser

1. subscription.active — Prenumerationen aktiveras
2. subscription.updated — Ett fält i prenumerationen ändrades
3. subscription.on_hold — En debitering för förnyelse eller planändring misslyckades
4. subscription.failed — Det gick inte att skapa prenumerationen (slutgiltigt; kunden måste prenumerera igen)
5. subscription.renewed — En återkommande debitering lyckades
6. subscription.past_due — En förnyelse misslyckades och respitperioden började; kunden behåller åtkomsten till past_due_ends_at
7. subscription.plan_changed — Planen uppgraderades, nedgraderades eller ändrades
8. subscription.cancelled — Prenumerationen avslutades
9. subscription.expired — Prenumerationen nådde slutet av sin löptid

​

Betalningsscenarier

1. subscription.active: medgivandet godkänns och prenumerationen aktiveras.
2. payment.succeeded: bekräftar den första debiteringen. Förvänta dig denna inom 2–10 minuter efter checkout.

1. Vid provperiodens start (checkout): subscription.active utlöses när betalningsmetoden har godkänts. Ingen återkommande debitering görs ännu. Den första riktiga debiteringen skjuts upp tills provperioden är slut.
2. Vid provperiodens slut: det återkommande beloppet debiteras och du får payment.succeeded tillsammans med subscription.renewed.

• subscription.renewed: utlöses vid varje faktureringscykel när förnyelsebetalningen dras, alltid tillsammans med payment.succeeded. Den innehåller även det uppdaterade next_billing_date.

1. Prenumerationsfel

• subscription.failed - Det gick inte att skapa prenumerationen eftersom ett medgivande inte kunde skapas.
• payment.failed - Anger en misslyckad betalning.

2. Prenumeration pausad

• subscription.on_hold - Prenumerationen pausas på grund av en misslyckad förnyelsebetalning eller en misslyckad debitering för planändring. Om ditt företag har en respitperiod flyttas en misslyckad förnyelse först till past_due (subscription.past_due), och flyttas till on_hold (eller cancelled, beroende på inställningarna för respitperioden) först när respitperioden löper ut. Se Subscription States.
• När en prenumeration pausas förnyas den inte automatiskt förrän betalningsmetoden har uppdaterats.

​

subscription.failed jämfört med subscription.on_hold

​

Hantera pausade prenumerationer

​

När prenumerationer pausas

• Förnyelsebetalningen misslyckas: Den automatiska förnyelsedebiteringen misslyckas på grund av otillräckliga medel, ett utgånget kort eller avslag från banken
• Debiteringen för planändring misslyckas: En omedelbar debitering vid uppgradering eller nedgradering av planen misslyckas
• Godkännande av betalningsmetoden misslyckas: Betalningsmetoden kan inte godkännas för återkommande debiteringar

​

Återaktivera pausade prenumerationer

1. Skapar en debitering för återstående skuld
2. Skapar en faktura för debiteringen
3. Behandlar betalningen med den nya betalningsmetoden
4. Återaktiverar prenumerationen till tillståndet active när betalningen lyckas

// Webhook handler
app.post('/webhooks/dodo', async (req, res) => {
  const event = req.body;
  
  if (event.type === 'subscription.on_hold') {
    const subscription = event.data;
    
    // Update subscription status in your database
    await updateSubscriptionStatus(subscription.subscription_id, 'on_hold');
    
    // Notify customer to update payment method
    await sendEmailToCustomer(subscription.customer_id, {
      subject: 'Payment Required - Subscription On Hold',
      message: 'Your subscription is on hold. Please update your payment method to continue service.'
    });
  }
  
  res.json({ received: true });
});

// Update with new payment method
const response = await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { type: 'new', return_url: 'https://example.com/return' }
});

// For on_hold subscriptions, a charge is automatically created
if (response.payment_id) {
  console.log('Charge created for remaining dues:', response.payment_id);
  // Redirect customer to response.payment_link to complete payment
}

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    payment_method={"type": "new", "return_url": "https://example.com/return"},
)

# For on_hold subscriptions, a charge is automatically created
if response.payment_id:
    print("Charge created for remaining dues:", response.payment_id)
    # Redirect customer to response.payment_link to complete payment

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  payment_method: { type: 'existing', payment_method_id: 'pm_abc123' }
});

if (event.type === 'payment.succeeded') {
  const payment = event.data;
  
  // Check if this payment is for an on_hold subscription
  if (payment.subscription_id) {
    // Wait for subscription.active webhook to confirm reactivation
  }
}

if (event.type === 'subscription.active') {
  const subscription = event.data;
  
  // Update subscription status in your database
  await updateSubscriptionStatus(subscription.subscription_id, 'active');
  
  // Restore customer access
  await restoreCustomerAccess(subscription.customer_id);
  
  // Notify customer of successful reactivation
  await sendEmailToCustomer(subscription.customer_id, {
    subject: 'Subscription Reactivated',
    message: 'Your subscription has been reactivated successfully.'
  });
}

​

Exempel på nyttolast för prenumerationshändelse

​

Ändra prenumerationsplaner

​

Alternativ för proportionell debitering

​

1. prorated_immediately

• Krediterar den oanvända delen av den aktuella faktureringscykeln, proportionellt efter återstående tid. Krediten täcker basplanen, kvantiteten och eventuella tillägg
• Debiterar sedan en hel cykel enligt den nya planen, kvantiteten och tilläggen. Själva debiteringen proportioneras aldrig
• Netto omedelbar debitering = (hel ny cykel) minus (återstående andel × hel gammal cykel). Om krediten är större hålls mellanskillnaden som prenumerationsspecifik kredit för framtida förnyelser
• Under en provperiod växlar detta omedelbart användaren till den nya planen och debiterar kunden direkt

​

2. full_immediately

• Debiterar kunden hela prenumerationsbeloppet för den nya planen utan kredit för den föregående cykeln
• Vid både uppgradering och nedgradering betalar kunden hela priset för den nya planen från början
• Användbart när du vill debitera hela beloppet oavsett hur mycket tid som återstod på den gamla planen

​

3. difference_immediately

• Kunden betalar endast skillnaden mellan priset för den gamla och den nya planen
• Beloppet beror inte på när under cykeln ändringen görs. Samma uppgradering kostar lika mycket dag 1 som dag 29
• Vid uppgradering debiteras kunden omedelbart skillnaden. Exempel: $30/månad → $80/månad = $50 debiteras direkt
• Vid nedgradering sparas prisskillnaden som prenumerationsspecifik kredit och används automatiskt vid framtida förnyelser. Exempel: $50/månad → $20/månad = $30 sparas som kredit

​

4. do_not_bill

• Tillämpa planändringen omedelbart utan att debitera något vid ändringstillfället. Den nya planen, kvantiteten och tilläggen kan användas direkt
• Eftersom inget debiteras nu får kunden vid en uppgradering den högre planen utan kostnad under resten av den aktuella cykeln. En nedgradering träder i kraft omedelbart utan kredit för den oanvända delen av cykeln som redan har betalats
• Tillägg som beviljats genom do_not_bill krediteras inte vid en senare planändring, eftersom de aldrig fakturerades. En efterföljande ändring fakturerar den nya mängden tillägg i sin helhet
• Den uppdaterade planen (och kvantiteten/tilläggen) faktureras vid nästa schemalagda förnyelse, och det ursprungliga faktureringsdatumet bevaras

​

Beteende

• När du anropar detta API initierar Dodo Payments omedelbart en debitering baserat på det valda alternativet för proportionell debitering
• Med prorated_immediately beräknas en kredit för den oanvända delen av den aktuella cykeln vid varje ändring, både uppgradering och nedgradering. Om krediten överstiger debiteringen för den nya cykeln läggs återstoden till prenumerationens kreditsaldo. Dessa krediter gäller endast den prenumerationen och används bara för att kvitta framtida återkommande betalningar för samma prenumeration
• Med difference_immediately är nettot alltid exakt prisskillnaden. Vid nedgraderingar sparas överskottet som prenumerationsspecifik kredit, på samma sätt som med prorated_immediately
• Alternativet full_immediately kringgår kreditberäkningar och debiterar hela beloppet för den nya planen
• Alternativet do_not_bill tillämpar ändringen omedelbart men skjuter upp faktureringen till nästa förnyelsedatum, som bevaras

​

Debiteringshantering

• Den omedelbara debitering som initieras när planen ändras slutförs vanligtvis på mindre än 2 minuter
• Om den omedelbara debiteringen misslyckas av någon anledning pausas prenumerationen automatiskt tills problemet är löst

​

On-Demand-prenumerationer

​

Viktigt att känna till om prenumerationsfakturering

​

Relaterad API-referens