Integrationsguide för prenumerationer

​

Förutsättningar

• Ett Dodo Payments handelskonto
• API-uppgifter (API-nyckel och webhook hemlig nyckel) från instrumentpanelen

​

API-integration

​

Utcheckningssessioner

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: 'prod_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": "prod_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: 'prod_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

​

Prenumerationseventtyper

1. subscription.active - Prenumerationen aktiveras framgångsrikt.
2. subscription.updated - Prenumerationsobjektet uppdaterades (utlöses vid alla fältändringar).
3. subscription.on_hold - Prenumerationen sätts på paus på grund av misslyckad förnyelse.
4. subscription.failed - Skapandet av prenumerationen misslyckades under skapandet av mandatet.
5. subscription.renewed - Prenumerationen förnyas för nästa faktureringsperiod.

​

Betalningsscenarier

1. subscription.active - Anger prenumerationsaktivering
2. payment.succeeded - Bekräftar den initiala betalningen:
   • För omedelbar fakturering (0 provdagar): Förvänta inom 2–10 minuter
   • För provdagar: när de avslutas
3. subscription.renewed - Indikerar att betalning dragits och förnyelse sker för nästa cykel. (I princip, när betalning dras för prenumerationsprodukter får du subscription.renewed webhook tillsammans med payment.succeeded)

1. Prenumerationsfel

• subscription.failed - Skapandet av prenumerationen misslyckades eftersom mandatet inte kunde skapas.
• payment.failed - Indikerar misslyckad betalning.

2. Prenumerationen pausas

• subscription.on_hold - Prenumerationen sätts på paus på grund av misslyckad förnyelsebetalning eller misslyckad avgift vid planändring.
• När en prenumeration pausas förnyas den inte automatiskt förrän betalningsmetoden uppdateras.

​

Hantera prenumeration på paus

​

När prenumerationer sätts på paus

• Förnyelsebetalning misslyckas: Den automatiska förnyelseavgiften misslyckas på grund av otillräckliga medel, utgången kort eller bankavslag
• Avgift vid planändring misslyckas: En omedelbar avgift under planuppgradering/nedgradering misslyckas
• Behörighet för betalningsmetod misslyckas: Betalningsmetoden kan inte auktoriseras för återkommande avgifter

​

Återaktivera prenumerationer från paus

1. Skapar en avgift för återstående skuld
2. Skapar en faktura för avgiften
3. Bearbetar betalningen med den nya betalningsmetoden
4. Återaktiverar prenumerationen till active-tillstånd efter lyckad betalning

// 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, {
  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
}

await client.subscriptions.updatePaymentMethod(subscriptionId, {
  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å prenumerationseventpayload

​

Ändra prenumerationsplaner

​

Prorationsalternativ

​

1. prorated_immediately

• Beräknar det pro rata-belopp som baseras på den återstående tiden i den nuvarande faktureringscykeln
• Debiterar kunden endast för skillnaden mellan den gamla och den nya planen
• Under en provperiod kommer detta omedelbart att byta användaren till den nya planen och debitera kunden direkt

​

2. full_immediately

• Debiterar kunden hela prenumerationsbeloppet för den nya planen
• Ignorerar kvarvarande tid eller krediter från den tidigare planen
• Användbart när du vill återställa faktureringscykeln eller debitera hela beloppet oberoende av proration

​

3. difference_immediately

• Vid uppgradering debiteras kunden omedelbart skillnaden mellan de två planbeloppen.
• Till exempel, om den nuvarande planen är 30 dollars och kunden uppgraderar till 80 dollars, debiteras 50 dollars direkt.
• Vid nedgradering läggs det oanvända beloppet från den aktuella planen till som intern kredit och appliceras automatiskt på framtida prenumerationsförnyelser.
• Till exempel, om den nuvarande planen är 50 dollars och kunden byter till en 20 dollars-plan, krediteras resterande 30 dollars och används för nästa faktureringscykel.

​

Beteende

• När du anropar detta API initierar Dodo Payments omedelbart en avgift baserat på ditt valda proration-alternativ
• Om planändringen är en nedgradering och du använder prorated_immediately, beräknas krediter automatiskt och läggs till prenumerationens kreditbalans. Dessa krediter är specifika för den prenumerationen och används endast för att kvitta framtida återkommande betalningar för samma prenumeration
• Alternativet full_immediately kringgår kreditberäkningar och debiterar hela det nya planbeloppet

​

Avgiftsbehandling

• Den omedelbara avgiften som initieras vid planändring slutförs vanligtvis inom mindre än 2 minuter
• Om denna omedelbara avgift misslyckas av någon anledning, sätts prenumerationen automatiskt på paus tills problemet är löst

​

On-Demand Prenumerationer