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 ändras
3. subscription.on_hold — En förnyelse- eller planändringsdebitering misslyckas
4. subscription.failed — Det gick inte att skapa prenumerationen (slutgiltigt; kunden måste prenumerera igen)
5. subscription.renewed — En återkommande debitering lyckas
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 debiteringscykel när förnyelsebetalningen dras, alltid tillsammans med payment.succeeded. Den innehåller även den 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. Prenumerationen pausad

• subscription.on_hold - Prenumerationen pausas på grund av en misslyckad förnyelsebetalning eller misslyckad planändringsdebitering. 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 Prenumerationstillstånd.
• 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 pausad prenumeration

​

När prenumerationer pausas

• Förnyelsebetalningen misslyckas: Den automatiska förnyelsedebiteringen misslyckas på grund av otillräckliga medel, utgånget kort eller avslag från banken
• Planändringsdebiteringen misslyckas: En omedelbar debitering vid upp- 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. Genererar 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 debiteringscykeln, proportionellt efter återstående tid. Krediten omfattar basplanen, antalet och eventuella tillägg
• Debiterar sedan en hel cykel enligt den nya planen, antalet och tilläggen. Själva debiteringen är aldrig proportionell
• Omedelbar nettodebitering = (full ny cykel) minus (återstående andel x full gammal cykel). Om krediten är större behålls mellanskillnaden som prenumerationsspecifik kredit för framtida förnyelser
• Under en provperiod byter 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 av 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 mellanskillnaden. Exempel: $30/månad → $80/månad = $50 debiteras direkt
• Vid nedgradering sparas prisskillnaden som prenumerationsspecifik kredit och används automatiskt för 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, antalet och tilläggen kan användas direkt
• Eftersom inget debiteras nu får kunden vid en uppgradering den dyrare planen gratis under återstoden av den aktuella cykeln. En nedgradering träder i kraft omedelbart utan kredit för den oanvända delen av cykeln som kunden redan har betalat för
• Tillägg som beviljas via do_not_bill krediteras inte vid en senare planändring, eftersom de aldrig debiterades. En efterföljande ändring debiterar hela den nya tilläggsmängden
• Den uppdaterade planen (samt antal/tillägg) debiteras vid nästa planerade förnyelse, och det ursprungliga debiteringsdatumet 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 resten till prenumerationens kreditbalans. Dessa krediter är specifika för prenumerationen och används endast för att kvitta framtida återkommande betalningar för samma prenumeration
• Med difference_immediately är nettot alltid den exakta 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 debiteringen till nästa förnyelsedatum, som bevaras

​

Debiteringshantering

• Den omedelbara debitering som initieras vid planändringen slutförs vanligtvis på mindre än 2 minuter
• Om denna omedelbara debitering misslyckas av någon anledning pausas prenumerationen automatiskt tills problemet har lösts

​

On-demand-prenumerationer

​

Viktigt att känna till om prenumerationsdebitering

​

Relaterad API-referens