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 tarde, creas cargos contra esa suscripción con montos personalizados utilizando el endpoint de cargo dedicado.
3. Escuchas los webhooks (por ejemplo, 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: Utiliza retroceso exponencial entre reintentos.
• Límites de reintento: Limita el total de reintentos (máximo de 3 a 4 intentos).
• Filtrado inteligente: Reintenta solo en fallos reintentables (por ejemplo, errores de red/emisor, fondos insuficientes); nunca reintentes rechazos duros.
• Prevención de pruebas de tarjeta: No reintentes fallos como DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
• Variar metadatos (opcional): Si mantienes tu propio sistema de reintento, diferencia los reintentos a través de metadatos (por ejemplo, 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 a la marca de tiempo de autorización original para evitar un comportamiento de “ráfaga” en tu cartera.
• Ejemplo: Si el cliente inicia una prueba o mandato a la 1:10 p. m. de hoy, programa los reintentos de seguimiento a la 1:10 p. m. en días posteriores según tu retroceso (por ejemplo, +3 días → 1:10 p. m., +7 días → 1:10 p. m.).
• Alternativamente, si almacenas el último tiempo de pago exitoso T, programa el próximo intento a T + X days para preservar la alineación de la hora del día.

​

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)

• Utiliza un programador/cola que persista marcas de tiempo precisas; calcula el próximo intento en el mismo desplazamiento de hora del día (por ejemplo, T + 3 days a la misma HH:MM).
• Mantén y referencia la última marca de tiempo de pago exitoso T para calcular el próximo intento; no agrupe múltiples suscripciones al mismo instante.
• Siempre evalúa la última razón de rechazo; detén los reintentos para rechazos duros en la lista de omisión anterior.
• Limita los reintentos concurrentes por cliente y por cuenta para evitar picos accidentales.
• Comunica proactivamente: envía un correo electrónico/SMS al cliente para actualizar su método de pago antes del próximo intento programado.
• Utiliza metadatos solo para observabilidad (por ejemplo, retry_attempt); nunca intentes “eludir” los sistemas de fraude/riesgo rotando campos irrelevantes.

​

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 Solicitud Inválida: Asegúrate de que on_demand.mandate_only se proporcione en la creación y product_price se proporcione para los cargos.
• Errores de moneda: Si anulas product_currency, confirma que sea compatible con tu cuenta y cliente.
• No se recibieron webhooks: Verifica tu URL de webhook y la configuración del secreto de firma.