Suscripciones bajo demanda

​

Descripción general

• Crear una suscripción bajo demanda (autorizar un mandato con un precio inicial opcional)
• Activar cargos posteriores con montos personalizados
• Rastrear resultados utilizando webhooks

​

Requisitos previos

• Cuenta de comerciante de Dodo Payments y clave API
• Secreto de webhook configurado y un endpoint para recibir eventos
• Un producto de suscripción en tu catálogo

​

Cómo funciona bajo demanda

1. Creas una suscripción con el objeto on_demand para autorizar un método de pago y, opcionalmente, cobrar un cargo inicial.
2. Más adelante, creas cargos contra esa suscripción con importes personalizados usando el endpoint dedicado de cargos.
3. Escuchas webhooks (p. ej., payment.succeeded, payment.failed) para actualizar tu sistema.

​

Crear una suscripción bajo demanda

​

Crear una suscripción bajo 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"
}

​

Cargar una suscripción bajo 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" }

​

Reintentos de pago

​

Principios para políticas de reintento seguras

• Mecanismo de retroceso: Usa retroceso exponencial entre reintentos.
• Límites de reintento: Limita los reintentos totales (máx. 3–4 intentos).
• Filtrado inteligente: Reintenta solo en fallos reintentables (p. ej., errores de red/emisor, fondos insuficientes); nunca reintentes rechazos definitivos.
• Prevención de pruebas de tarjetas: No reintentes fallos como DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
• Varía los metadatos (opcional): Si mantienes tu propio sistema de reintentos, diferencia los reintentos mediante metadatos (p. ej., retry_attempt).

​

Cronograma de reintentos sugerido (suscripciones)

• 1er intento: Inmediato cuando creas el cargo
• 2do intento: Después de 3 días
• 3er intento: Después de 7 días más (10 días en total)
• 4to intento (final): Después de otros 7 días (17 días en total)

​

Evita reintentos en ráfaga; alinea al tiempo de autorización

• Ancla los reintentos al sello de tiempo original de autorización para evitar comportamientos de “ráfaga” en todo tu portafolio.
• Ejemplo: si el cliente inicia una prueba o mandato a la 1:10 p. m. de hoy, programa reintentos de seguimiento a la 1:10 p. m. en días posteriores según tu retroceso (p. ej., +3 días → 1:10 p. m., +7 días → 1:10 p. m.).
• Alternativamente, si almacenas la hora del último pago exitoso T, programa el próximo intento en T + X days para mantener la alineación horaria.

​

Códigos de rechazo que no debes reintentar

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

​

Directrices de implementación (sin código)

• Usa un programador/cola que persista sellos de tiempo precisos; calcula el próximo intento en el mismo desplazamiento de hora del día exacto (p. ej., T + 3 days a la misma HH:MM).
• Mantén y consulta el sello de tiempo del último pago exitoso T para calcular el siguiente intento; no aglomeres múltiples suscripciones al mismo instante.
• Evalúa siempre la última razón de rechazo; detén los reintentos para rechazos definitivos en la lista de exclusión anterior.
• Limita los reintentos simultáneos por cliente y por cuenta para evitar aumentos accidentales.
• Comunica de forma proactiva: envía un correo electrónico/SMS al cliente para que actualice su método de pago antes del siguiente intento programado.
• Usa metadatos solo para observabilidad (p. ej., retry_attempt); nunca intentes “evadir” los sistemas de fraude/riesgo rotando campos sin importancia.

​

Rastrear resultados con webhooks

• subscription.active: Mandato autorizado y suscripción activada
• subscription.failed: Creación fallida (por ejemplo, fallo del mandato)
• subscription.on_hold: Suscripción en espera (por ejemplo, estado impago)
• payment.succeeded: Cargo exitoso
• payment.failed: Cargo fallido

​

Pruebas y próximos pasos

​

Solución de problemas

• 422 Invalid Request: Asegúrate de que on_demand.mandate_only se proporciona al crear y product_price se proporciona para los cargos.
• Errores de moneda: Si anulas product_currency, confirma que está soportado para tu cuenta y cliente.
• No se reciben webhooks: Verifica la configuración de tu URL de webhook y el secreto de firma.