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: '[email protected]',
      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": "[email protected]",
        "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: '[email protected]',
      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 har aktiverats framgångsrikt.
2. subscription.updated - Prenumerationsobjektet har uppdaterats (utlöses vid ändring av något fält).
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 - Indikerar aktivering av prenumerationen
2. payment.succeeded - Bekräftar den första betalningen:
   • För omedelbar fakturering (0 provdagar): Förvänta dig inom 2-10 minuter
   • För provdagar: när det slutar
3. subscription.renewed - Indikerar betalningsavdrag och förnyelse för nästa cykel. (I grund och botten, 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 på grund av misslyckande att skapa ett mandat.
• payment.failed - Indikerar misslyckad betalning.

2. Prenumeration på paus

• subscription.on_hold - Prenumerationen sätts på paus på grund av misslyckad förnyelsebetalning eller misslyckad avgift vid planändring.
• När en prenumeration sätts på paus kommer den inte att förnyas 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 utestående belopp
2. Genererar en faktura för avgiften
3. Behandlar 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 proraterade beloppet baserat på den återstående tiden i den aktuella faktureringscykeln
• Tar ut avgift från kunden endast för skillnaden mellan den gamla och den nya planen
• Under en provperiod kommer detta omedelbart att växla användaren till den nya planen och ta ut avgift från kunden direkt

​

2. full_immediately

• Tar ut avgift från kunden för hela prenumerationsbeloppet för den nya planen
• Ignorerar eventuell återstående tid eller krediter från den tidigare planen
• Användbart när du vill återställa faktureringscykeln eller ta ut hela beloppet oavsett proration

​

3. difference_immediately

• Vid uppgradering debiteras kunden omedelbart skillnaden mellan de två planbeloppen.
• Till exempel, om den nuvarande planen är 30 Dollar och kunden uppgraderar till 80 Dollar, debiteras de $50 direkt.
• Vid nedgradering läggs det oanvända beloppet från den nuvarande planen som intern kredit och tillämpas automatiskt på framtida prenumerationsförnyelser.
• Till exempel, om den nuvarande planen är 50 Dollar och kunden byter till en 20 Dollar-plan, krediteras de återstående $30 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 prorationsalternativ
• Om planändringen är en nedgradering och du använder prorated_immediately, kommer krediter automatiskt att beräknas och läggas till prenumerationens kreditbalans. Dessa krediter är specifika för den prenumerationen och kommer endast att användas för att kompensera framtida återkommande betalningar av samma prenumeration
• Alternativet full_immediately kringgår kreditberäkningar och debiterar hela beloppet för den nya planen

​

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