Guia de Integração de Assinaturas

​

Pré-requisitos

• Uma conta de comerciante do Dodo Payments
• Credenciais da API (chave da API e chave secreta do webhook) do painel

​

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

​

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 - Assinatura ativada com sucesso.
2. subscription.updated - O objeto de assinatura foi atualizado (dispara em qualquer alteração de campo).
3. subscription.on_hold - Assinatura é colocada em espera devido à renovação com falha.
4. subscription.failed - A criação da assinatura falhou durante a criação do mandato.
5. subscription.renewed - Assinatura foi renovada para o próximo ciclo de cobrança.

​

Cenários de Pagamento

1. subscription.active - Indica ativação da assinatura
2. payment.succeeded - Confirma o pagamento inicial:
   • Para cobrança imediata (0 dias de teste): espere entre 2-10 minutos
   • Para dias de teste: assim que o período terminar
3. subscription.renewed - Indica dedução de pagamento e renovação para o próximo ciclo. (Basicamente, sempre que o pagamento for debitado para produtos de assinatura, você receberá o webhook subscription.renewed junto com payment.succeeded)

1. Falha na Assinatura

• subscription.failed - A criação da assinatura falhou devido à falha na criação do mandato.
• payment.failed - Indica pagamento falhou.

2. Assinatura em Espera

• subscription.on_hold - A assinatura é colocada em espera devido ao pagamento de renovação falho ou falha na cobrança da alteração de plano.
• Quando uma assinatura entra em espera, ela não será renovada automaticamente até que o método de pagamento seja atualizado.

​

Tratando Assinaturas Suspensas

​

Quando as Assinaturas São Suspensas

• O pagamento de renovação falha: A cobrança automática de renovação falha devido a fundos insuficientes, cartão expirado ou recusa do banco
• A cobrança de mudança de plano falha: Uma cobrança imediata durante a atualização/diminuição do plano falha
• A autorização do método de pagamento falha: O método de pagamento não pode ser autorizado para cobranças recorrentes

​

Reativando Assinaturas Suspensas

1. Cria uma cobrança pelos valores restantes
2. Gera uma fatura para a cobrança
3. Processa o pagamento usando o novo método de pagamento
4. Reativa a assinatura para o estado active após o 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, {
  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.'
  });
}

​

Exemplo de payload de evento de Assinatura

​

Mudando Planos de Assinatura

​

Opções de Prorrata

​

1. prorated_immediately

• Calcula o valor proporcional com base no tempo restante no ciclo de cobrança atual
• Cobra o cliente apenas pela diferença entre o plano antigo e o novo
• Durante um período de teste, isso mudará imediatamente o usuário para o novo plano, cobrando o cliente na hora

​

2. full_immediately

• Cobra o cliente o valor total da nova assinatura
• Ignora qualquer tempo restante ou créditos do plano anterior
• Útil quando você deseja redefinir o ciclo de cobrança ou cobrar o valor integral independentemente da prorrata

​

3. difference_immediately

• Ao fazer um upgrade, o cliente é cobrado imediatamente pela diferença entre os valores dos dois planos.
• Por exemplo, se o plano atual custa 30 dólares e o cliente fazer upgrade para 80 dólares, ele será cobrado instantaneamente em 50 dólares.
• Ao fazer downgrade, o valor não utilizado do plano atual é adicionado como crédito interno e automaticamente aplicado às futuras renovações da assinatura.
• Por exemplo, se o plano atual custa 50 dólares e o cliente mudar para um plano de 20 dólares, os 30 dólares restantes são creditados e usados para o próximo ciclo de cobrança.

​

Comportamento

• Ao invocar esta API, a Dodo Payments inicia imediatamente uma cobrança com base na opção de prorrata selecionada
• Se a mudança de plano for um downgrade e você utilizar prorated_immediately, os créditos serão calculados automaticamente e adicionados ao saldo de créditos da assinatura. Esses créditos são específicos daquela assinatura e serão usados apenas para compensar futuros pagamentos recorrentes da mesma assinatura
• A opção full_immediately ignora os cálculos de crédito e cobra o valor completo do novo plano

​

Processamento de Cobrança

• A cobrança imediata iniciada na mudança de plano geralmente é processada em menos de 2 minutos
• Se essa cobrança imediata falhar por qualquer motivo, a assinatura é automaticamente suspensa até que o problema seja resolvido

​

Assinaturas Sob Demanda