Subscription Integration Guide

​

Pré-requisitos

• Uma conta de comerciante do Dodo Payments
• Uma chave de API em Developer → API Keys no dashboard, armazenada em DODO_PAYMENTS_API_KEY
• Um segredo de webhook em Developer → Webhooks, armazenado em DODO_PAYMENTS_WEBHOOK_KEY
• Pelo menos um produto de assinatura criado em Products

​

Integração da API

​

Sessões de Checkout

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);

​

Resposta da API

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

​

Webhooks

​

Tipos de eventos de assinatura

1. subscription.active — A assinatura foi ativada
2. subscription.updated — Um campo da assinatura foi alterado
3. subscription.on_hold — Uma cobrança de renovação ou alteração de plano falhou
4. subscription.failed — A criação da assinatura falhou (terminal; o cliente precisa assinar novamente)
5. subscription.renewed — Uma cobrança recorrente foi bem-sucedida
6. subscription.past_due — Uma renovação falhou e o período de carência começou; o cliente mantém o acesso até past_due_ends_at
7. subscription.plan_changed — O plano foi atualizado, reduzido ou alterado
8. subscription.cancelled — A assinatura foi cancelada
9. subscription.expired — A assinatura chegou ao fim do prazo

​

Cenários de pagamento

1. subscription.active: o mandato é autorizado e a assinatura é ativada.
2. payment.succeeded: confirma a primeira cobrança. Espere recebê-lo em até 2–10 minutos após o checkout.

1. No início do teste (checkout): subscription.active é disparado quando a forma de pagamento é autorizada. Nenhuma cobrança recorrente é feita ainda. A primeira cobrança real é adiada até o fim do teste.
2. No fim do teste: o valor recorrente é cobrado, e você recebe payment.succeeded junto com subscription.renewed.

• subscription.renewed: é disparado a cada ciclo de cobrança quando o pagamento da renovação é debitado, sempre junto com payment.succeeded. Ele também inclui o next_billing_date atualizado.

1. Falha da assinatura

• subscription.failed - A criação da assinatura falhou porque não foi possível criar um mandato.
• payment.failed - Indica falha no pagamento.

2. Assinatura suspensa

• subscription.on_hold - A assinatura foi suspensa devido a uma falha no pagamento da renovação ou da cobrança de alteração de plano. Se sua empresa tiver um período de carência, uma renovação com falha primeiro move a assinatura para past_due (subscription.past_due), e ela é movida para on_hold (ou cancelled, dependendo das configurações do período de carência) somente quando o período termina. Consulte Estados da assinatura.
• Quando uma assinatura é suspensa, ela não será renovada automaticamente até que a forma de pagamento seja atualizada.

​

subscription.failed vs. subscription.on_hold

​

Como lidar com uma assinatura suspensa

​

Quando as assinaturas são suspensas

• O pagamento da renovação falha: a cobrança automática da renovação falha devido a fundos insuficientes, cartão expirado ou recusa do banco
• A cobrança de alteração de plano falha: uma cobrança imediata durante a atualização ou redução do plano falha
• A autorização da forma de pagamento falha: não é possível autorizar a forma de pagamento para cobranças recorrentes

​

Reativação de assinaturas suspensas

1. Cria uma cobrança pelos valores pendentes
2. Gera uma invoice para a cobrança
3. Processa o pagamento usando a nova forma de pagamento
4. Reativa a assinatura para o estado active após um pagamento bem-sucedido

// 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.'
  });
}

​

Exemplo de payload de evento de assinatura

​

Alteração de planos de assinatura

​

Opções de proration

​

1. prorated_immediately

• Credita a parte não utilizada do ciclo de cobrança atual, calculada proporcionalmente ao tempo restante. O crédito cobre o plano base, a quantidade e quaisquer add-ons
• Em seguida, cobra um ciclo completo no novo plano, quantidade e add-ons. A cobrança em si nunca é calculada proporcionalmente
• Cobrança imediata líquida = (novo ciclo completo) menos (fração restante x ciclo antigo completo). Se o crédito for maior, a diferença é mantida como crédito vinculado à assinatura para futuras renovações
• Durante um período de teste, isso muda imediatamente o usuário para o novo plano e cobra o cliente na hora

​

2. full_immediately

• Cobra do cliente o valor total da assinatura do novo plano, sem crédito pelo ciclo anterior
• Tanto na atualização quanto na redução, o cliente paga o preço integral do novo plano desde o início
• Útil quando você deseja cobrar o valor total independentemente de quanto tempo restava no plano antigo

​

3. difference_immediately

• O cliente paga apenas a diferença entre o preço do plano antigo e o novo
• O valor não depende do momento do ciclo em que a alteração é feita. A mesma atualização custa o mesmo no dia 1 e no dia 29
• Ao atualizar, o cliente é cobrado imediatamente pela diferença. Por exemplo, $30/mês → $80/mês = $50 cobrados na hora
• Ao reduzir, a diferença de preço é armazenada como crédito vinculado à assinatura e aplicada automaticamente a futuras renovações. Por exemplo, $50/mês → $20/mês = $30 armazenados como crédito

​

4. do_not_bill

• Aplica a alteração do plano imediatamente, mas não cobra nada no momento da alteração. O novo plano, a quantidade e os add-ons ficam disponíveis imediatamente
• Como nada é cobrado agora, uma atualização oferece ao cliente o plano superior gratuitamente pelo restante do ciclo atual. Uma redução entra em vigor imediatamente, sem crédito pela parte não utilizada do ciclo que já foi paga
• Add-ons concedidos por meio de do_not_bill não recebem crédito em uma alteração posterior de plano, pois nunca foram cobrados. Uma alteração subsequente cobra integralmente a nova quantidade de add-ons
• O plano atualizado (e a quantidade/add-ons) é cobrado na próxima renovação programada, e a data de cobrança original é preservada

​

Comportamento

• Quando você chama essa API, o Dodo Payments inicia imediatamente uma cobrança com base na opção de proration selecionada
• Com prorated_immediately, um crédito pela parte não utilizada do ciclo atual é calculado a cada alteração, tanto para atualização quanto para redução. Se esse crédito exceder a cobrança do novo ciclo, o restante será adicionado ao saldo de crédito da assinatura. Esses créditos são específicos dessa assinatura e só serão usados para compensar futuros pagamentos recorrentes da mesma assinatura
• Com difference_immediately, o valor líquido é sempre a diferença exata de preço. Para reduções, o excedente é armazenado como crédito vinculado à assinatura, assim como em prorated_immediately
• A opção full_immediately ignora os cálculos de crédito e cobra o valor total do novo plano
• A opção do_not_bill aplica a alteração imediatamente, mas adia a cobrança para a próxima data de renovação, que é preservada

​

Processamento da cobrança

• A cobrança imediata iniciada após a alteração do plano normalmente termina de ser processada em menos de 2 minutos
• Se essa cobrança imediata falhar por qualquer motivo, a assinatura será automaticamente suspensa até que o problema seja resolvido

​

Assinaturas sob demanda

​

Principais informações sobre a cobrança de assinaturas

​

Referência de API relacionada