Assinaturas Sob Demanda

​

Visão Geral

• Criar uma assinatura sob demanda (autorizar um mandato com preço inicial opcional)
• Acionar cobranças subsequentes com valores personalizados
• Rastrear resultados usando webhooks

​

Pré-requisitos

• Conta de comerciante Dodo Payments e chave de API
• Segredo do webhook configurado e um endpoint para receber eventos
• Um produto de assinatura em seu catálogo

​

Como funciona a assinatura sob demanda

1. Você cria uma assinatura com o objeto on_demand para autorizar um método de pagamento e opcionalmente coletar uma cobrança inicial.
2. Depois, você gera cobranças para essa assinatura com valores personalizados usando o endpoint dedicado de cobrança.
3. Você monitora webhooks (por exemplo, payment.succeeded, payment.failed) para atualizar seu sistema.

​

Criar uma assinatura sob demanda

​

Criar uma assinatura sob demanda

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 subscription = await client.checkoutSessions.create({
    product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
    billing_address:  { city: 'SF', country: 'US', state: 'CA', street: '1 Market St', zipcode: '94105' },
    customer: { customer_id: 'cus_123' },
    return_url: 'https://example.com/billing/success',
    subscription_data: {
        on_demand: {
            mandate_only: true // set false to collect an initial charge
            // product_price: 1000, // optional: charge $10.00 now if mandate_only is false
            // product_currency: 'USD',
            // product_description: 'Custom initial charge',
            // adaptive_currency_fees_inclusive: false,
        }
    }
  });

  console.log(subscription.checkout_url);
}

main().catch(console.error);

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get('DODO_PAYMENTS_API_KEY'),
    environment="test_mode",  # defaults to "live_mode"
)

checkout = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "pdt_123", "quantity": 1}
    ],
    billing_address={
        "city": "SF",
        "country": "US",
        "state": "CA",
        "street": "1 Market St",
        "zipcode": "94105",
    },
    customer={
        "customer_id": "cus_123",
    },
    return_url="https://example.com/billing/success",
    subscription_data={
      "on_demand":{
      "mandate_only": True,  # set False to collect an initial charge
      # "product_price": 1000,  # optional: charge $10.00 now if mandate_only is false
      # "product_currency": "USD",
      # "product_description": "Custom initial charge",
      # "adaptive_currency_fees_inclusive": False,
      }
    },
)

print(checkout.checkout_url)

package main

import (
    "fmt"
    "os"

    dodo "github.com/dodopayments/dodopayments-go"
)

func main() {
    client := dodo.NewClient(dodo.Config{
        BearerToken: os.Getenv("DODO_PAYMENTS_API_KEY"),
        Environment: dodo.TestMode, // defaults to LiveMode
    })

    checkout, err := client.CheckoutSessions.Create(dodo.CheckoutSessionCreateParams{
        ProductCart: []dodo.ProductCartItem{
            {
                ProductID: "pdt_123",
                Quantity:  1,
            },
        },
        BillingAddress: &dodo.BillingAddress{
            City:    "SF",
            Country: "US",
            State:   "CA",
            Street:  "1 Market St",
            Zipcode: "94105",
        },
        Customer: &dodo.CustomerRef{
            CustomerID: "cus_123",
        },
        ReturnURL: "https://example.com/billing/success",
        SubscriptionData: &dodo.SubscriptionData{
            OnDemand: &dodo.OnDemandSubscription{
                MandateOnly: true, // set false to collect an initial charge
                // ProductPrice: 1000,  // optional: charge $10.00 now if mandate_only is false
                // ProductCurrency: "USD",
                // ProductDescription: "Custom initial charge",
                // AdaptiveCurrencyFeesInclusive: false,
            },
        },
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(checkout.CheckoutURL)
}

curl -X POST "$DODO_API/checkouts" \
  -H "Authorization: Bearer $DODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [
      {
        "product_id": "pdt_123",
        "quantity": 1
      }
    ],
    "customer": {
      "customer_id": "cus_123"
    },
    "billing_address": {
      "street": "1 Market St",
      "city": "SF",
      "state": "CA",
      "country": "US",
      "zipcode": "94105"
    },
    "subscription_data": {
      "on_demand": {
        "mandate_only": true
      }
    },
    "return_url": "https://example.com/billing/success"
  }'

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

​

Cobrar uma assinatura sob demanda

import DodoPayments from 'dodopayments';

const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY });

async function chargeNow(subscriptionId) {
  const res = await client.subscriptions.charge(subscriptionId, { product_price: 2500 });
  console.log(res.payment_id);
}

chargeNow('sub_123').catch(console.error);

import os
from dodopayments import DodoPayments

client = DodoPayments(bearer_token=os.environ.get('DODO_PAYMENTS_API_KEY'))

response = client.subscriptions.charge(
    subscription_id="sub_123",
    product_price=2500,
)

print(response.payment_id)

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(option.WithBearerToken("YOUR_API_KEY"))
  res, err := client.Subscriptions.Charge(context.TODO(), "sub_123", dodopayments.SubscriptionChargeParams{
    ProductPrice: dodopayments.F(int64(2500)),
  })
  if err != nil { panic(err) }
  fmt.Println(res.PaymentID)
}

curl -X POST "$DODO_API/subscriptions/sub_123/charge" \
  -H "Authorization: Bearer $DODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_price": 2500,
    "product_description": "Extra usage for March"
  }'

{ "payment_id": "pay_abc123" }

​

Tentativas de pagamento

​

Princípios para políticas de tentativas seguras

• Mecanismo de retrocesso: use retrocesso exponencial entre as tentativas.
• Limites de tentativas: limite o total de tentativas (máximo de 3 a 4 tentativas).
• Filtragem inteligente: reitere apenas em falhas passíveis de nova tentativa (por exemplo, erros de rede/emitente, fundos insuficientes); nunca reitere recusas definitivas.
• Prevenção de testes de cartão: não reitere falhas como DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
• Variação de metadados (opcional): se você mantiver seu próprio sistema de tentativa, diferencie as tentativas via metadados (por exemplo, retry_attempt).

​

Cronograma de tentativas sugerido (assinaturas)

• 1ª tentativa: Imediata quando você cria a cobrança
• 2ª tentativa: Após 3 dias
• 3ª tentativa: Após mais 7 dias (10 dias no total)
• 4ª tentativa (final): Após mais 7 dias (17 dias no total)

​

Evite tentativas em massa; alinhe-se ao horário de autorização

• Víncule as tentativas ao timestamp de autorização original para evitar comportamento de “rajada” em seu portfólio.
• Exemplo: se o cliente iniciar um teste ou mandato às 13h10 de hoje, agende as tentativas de acompanhamento às 13h10 nos dias seguintes conforme seu retrocesso (por exemplo, +3 dias → 13h10, +7 dias → 13h10).
• Alternativamente, se você armazenar o horário do último pagamento bem-sucedido T, agende a próxima tentativa em T + X days para preservar o alinhamento do horário do dia.

​

Códigos de recusa que você não deve tentar novamente

• STOLEN_CARD
• DO_NOT_HONOR
• FRAUDULENT
• PICKUP_CARD
• AUTHENTICATION_FAILURE
• LOST_CARD

​

Diretrizes de implementação (sem código)

• Use um agendador/fila que persista timestamps precisos; calcule a próxima tentativa no deslocamento exato do horário do dia (por exemplo, T + 3 days no mesmo HH:MM).
• Mantenha e consulte o timestamp do último pagamento bem-sucedido T para calcular a próxima tentativa; não agrupe várias assinaturas no mesmo instante.
• Sempre avalie o motivo da última recusa; interrompa as tentativas em recusas definitivas da lista acima.
• Limite as tentativas simultâneas por cliente e por conta para evitar surtos acidentais.
• Comunique proativamente: envie e-mail/SMS ao cliente para atualizar seu método de pagamento antes da próxima tentativa agendada.
• Use metadados apenas para observabilidade (por exemplo, retry_attempt); nunca tente “evadir” sistemas de fraude/risco rotacionando campos inconsequentes.

​

Rastrear resultados com webhooks

• subscription.active: Mandato autorizado e assinatura ativada
• subscription.failed: Criação falhou (por exemplo, falha de mandato)
• subscription.on_hold: Assinatura colocada em espera (por exemplo, estado não pago)
• payment.succeeded: Cobrança bem-sucedida
• payment.failed: Cobrança falhou

​

Testes e próximos passos

​

Solução de problemas

• 422 Invalid Request: garanta que on_demand.mandate_only seja fornecido na criação e product_price seja fornecido para cobranças.
• Erros de moeda: se você sobrescrever product_currency, confirme se ela é compatível com sua conta e cliente.
• Nenhum webhook recebido: verifique sua URL de webhook e a configuração do segredo de assinatura.