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: medgivandet auktoriseras och prenumerationen aktiveras.
2. payment.succeeded: bekräftar den första debiteringen. Förvänta dig detta inom 2–10 minuter efter checkout.

1. Vid provperiodens start (checkout): subscription.active utlöses när betalningsmetoden har auktoriserats. 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 tar emot payment.succeeded tillsammans med subscription.renewed.

• subscription.renewed: utlöses vid varje faktureringsperiod 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. Prenumeration pausad

• subscription.on_hold – Prenumerationen pausas på grund av en misslyckad förnyelsebetalning eller en misslyckad debitering för planändring.
• 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, ett utgånget kort eller att banken nekar betalningen
• Debiteringen för planändringen misslyckas: En omedelbar debitering under en upp- eller nedgradering av planen misslyckas
• Auktorisering av betalningsmetoden misslyckas: Betalningsmetoden kan inte auktoriseras för återkommande debiteringar

​

Återaktivera prenumerationer från pausat tillstånd

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

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

# Update with new payment method
response = client.subscriptions.update_payment_method(
    subscription_id=subscription_id,
    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, {
  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å payload för prenumerationshändelse

​

Ändra prenumerationsplaner

​

Alternativ för proportionell debitering

​

1. prorated_immediately

• Beräknar det proportionella beloppet baserat på den återstående tiden i den aktuella faktureringsperioden
• Debiterar kunden endast skillnaden mellan den gamla och den nya planen
• Under en provperiod växlar användaren omedelbart till den nya planen och kunden debiteras direkt

​

2. full_immediately

• Debiterar kunden hela prenumerationsbeloppet för den nya planen
• Ignorerar eventuell återstående tid eller krediter från den föregående planen
• Användbart när du vill återställa faktureringsperioden eller debitera hela beloppet oavsett proportionell debitering

​

3. difference_immediately

• Vid uppgradering debiteras kunden omedelbart skillnaden mellan de två planbeloppen.
• Om den aktuella planen till exempel kostar 30 dollar och kunden uppgraderar till en plan på 80 dollar debiteras de $50 direkt.
• Vid nedgradering läggs det outnyttjade beloppet från den aktuella planen till som en intern kredit och används automatiskt vid framtida förnyelser av prenumerationen.
• Om den aktuella planen till exempel kostar 50 dollar och kunden byter till en plan på 20 dollar krediteras de återstående $30 och används under nästa faktureringsperiod.

​

4. do_not_bill

• Tillämpas planändringen omedelbart men debiterar ingenting vid ändringstillfället.
• Den uppdaterade planen (samt antal/tillägg) 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
• Om planändringen är en nedgradering och du använder prorated_immediately beräknas krediter automatiskt och läggs till i prenumerationens kreditsaldo. Dessa krediter gäller endast den prenumerationen och används bara för att kvitta framtida återkommande betalningar för samma prenumeration
• Alternativet full_immediately kringgår kreditberäkningar och debiterar hela beloppet för den nya planen

​

Debiteringsbehandling

• Den omedelbara debiteringen 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 prenumerationsfakturering

​

Relaterad API-referens