Saltar al contenido principal
El SDK de TypeScript proporciona acceso conveniente del lado del servidor a la API REST de Dodo Payments para aplicaciones de TypeScript y JavaScript. Cuenta con definiciones de tipos completas, manejo de errores, reintentos, tiempos de espera y auto-paginación para un procesamiento de pagos sin problemas.

​
Instalación

Instala el SDK usando tu gestor de paquetes preferido: 
npm install dodopayments

​
Inicio Rápido

Inicializa el cliente con tu clave API y comienza a procesar pagos: 
import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env['DODO_PAYMENTS_API_KEY'], // This is the default and can be omitted
  environment: 'test_mode', // defaults to 'live_mode'
});

const checkoutSessionResponse = await client.checkoutSessions.create({
  product_cart: [{ product_id: 'product_id', quantity: 1 }],
});

console.log(checkoutSessionResponse.session_id);
Siempre almacena tus claves API de forma segura utilizando variables de entorno. Nunca las comites en el control de versiones ni las expongas en el código del lado del cliente.

​
Características Principales

TypeScript Primero

Soporte completo de TypeScript con definiciones de tipos completas para todos los endpoints de la API

Auto-Paginación

La paginación automática para respuestas de lista hace que trabajar con grandes conjuntos de datos sea fácil

Manejo de Errores

Tipos de error integrados con mensajes detallados para diferentes escenarios de fallo

Reintentos Inteligentes

Reintentos automáticos configurables con retroceso exponencial para errores transitorios

​
Configuración

​
Variables de Entorno

Establece variables de entorno para una configuración segura:
.env
DODO_PAYMENTS_API_KEY=your_api_key_here

​
Configuración de Tiempo de Espera

Configura los tiempos de espera de las solicitudes a nivel global o por solicitud: 
// Configure default timeout for all requests (default is 1 minute)
const client = new DodoPayments({
  timeout: 20 * 1000, // 20 seconds
});

// Override per-request
await client.checkoutSessions.create(
  { product_cart: [{ product_id: 'product_id', quantity: 0 }] },
  { timeout: 5 * 1000 }
);

​
Configuración de Reintentos

Configura el comportamiento de reintentos automáticos: 
// Configure default for all requests (default is 2 retries)
const client = new DodoPayments({
  maxRetries: 0, // disable retries
});

// Override per-request
await client.checkoutSessions.create(
  { product_cart: [{ product_id: 'product_id', quantity: 0 }] },
  { maxRetries: 5 }
);
El SDK reintenta automáticamente las solicitudes que fallan debido a errores de red o problemas del servidor (respuestas 5xx) con retroceso exponencial.

​
Operaciones Comunes

​
Crear una Sesión de Pago

Genera una sesión de pago para recopilar información de pago: 
const session = await client.checkoutSessions.create({
  product_cart: [
    {
      product_id: 'prod_123',
      quantity: 1
    }
  ],
  return_url: 'https://yourdomain.com/return'
});

console.log('Redirect to:', session.url);

​
Gestionar Clientes

Crea y recupera información de clientes: 
// Create a customer
const customer = await client.customers.create({
  email: '[email protected]',
  name: 'John Doe',
  metadata: {
    user_id: '12345'
  }
});

// Retrieve customer
const retrieved = await client.customers.retrieve('cus_123');
console.log(`Customer: ${retrieved.name} (${retrieved.email})`);

​
Manejar Suscripciones

Crea y gestiona suscripciones recurrentes: 
// Create a subscription
const subscription = await client.subscriptions.create({
  customer_id: 'cus_123',
  product_id: 'prod_456',
  price_id: 'price_789'
});

// Retrieve subscription usage history
const usageHistory = await client.subscriptions.retrieveUsageHistory('sub_123', {
  start_date: '2024-01-01T00:00:00Z',
  end_date: '2024-03-31T23:59:59Z'
});

​
Facturación Basada en Uso

​
Ingesta de Eventos de Uso

Rastrea eventos personalizados para la facturación basada en uso: 
await client.usageEvents.ingest({
  events: [
    {
      event_id: 'api_call_12345',
      customer_id: 'cus_abc123',
      event_name: 'api_request',
      timestamp: '2024-01-15T10:30:00Z',
      metadata: {
        endpoint: '/api/v1/users',
        method: 'GET',
        tokens_used: '150'
      }
    }
  ]
});
Los eventos deben tener valores únicos event_id para la idempotencia. Los IDs duplicados dentro de la misma solicitud son rechazados, y las solicitudes posteriores con IDs existentes son ignoradas.

​
Recuperar Eventos de Uso

Obtén información detallada sobre eventos de uso: 
// Get a specific event
const event = await client.usageEvents.retrieve('api_call_12345');

// List events with filtering
const events = await client.usageEvents.list({
  customer_id: 'cus_abc123',
  event_name: 'api_request',
  start: '2024-01-14T10:30:00Z',
  end: '2024-01-15T10:30:00Z'
});

​
Configuración de Proxy

Configura la configuración del proxy para diferentes entornos de ejecución:

​
Node.js (usando undici)

import DodoPayments from 'dodopayments';
import * as undici from 'undici';

const proxyAgent = new undici.ProxyAgent('http://localhost:8888');
const client = new DodoPayments({
  fetchOptions: {
    dispatcher: proxyAgent,
  },
});

​
Bun

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  fetchOptions: {
    proxy: 'http://localhost:8888',
  },
});

​
Deno

import DodoPayments from 'npm:dodopayments';

const httpClient = Deno.createHttpClient({ proxy: { url: 'http://localhost:8888' } });
const client = new DodoPayments({
  fetchOptions: {
    client: httpClient,
  },
});

​
Registro

Controla la verbosidad del registro usando variables de entorno u opciones del cliente: 
// Via client option
const client = new DodoPayments({
  logLevel: 'debug', // Show all log messages
});

# Via environment variable
export DODO_PAYMENTS_LOG=debug
Niveles de registro disponibles:
  • 'debug' - Muestra mensajes de depuración, información, advertencias y errores
  • 'info' - Muestra mensajes de información, advertencias y errores
  • 'warn' - Muestra advertencias y errores (predeterminado)
  • 'error' - Muestra solo errores
  • 'off' - Desactiva todos los registros
En el nivel de depuración, se registran todas las solicitudes y respuestas HTTP, incluidos los encabezados y cuerpos. Algunos encabezados de autenticación son redactados, pero los datos sensibles en los cuerpos pueden seguir siendo visibles.

​
Migración desde el SDK de Node.js

Si estás actualizando desde el SDK de Node.js legado, el SDK de TypeScript ofrece una mejor seguridad de tipos y características:

Ver Guía de Migración

Aprende cómo migrar del SDK de Node.js al SDK de TypeScript

​
Recursos

Repositorio de GitHub

Ver el código fuente y contribuir

Referencia de API

Documentación completa de la API

Comunidad de Discord

Obtén ayuda y conéctate con desarrolladores

Reportar Problemas

Reporta errores o solicita características

​
Soporte

¿Necesitas ayuda con el SDK de TypeScript?

​
Contribuyendo

¡Damos la bienvenida a las contribuciones! Consulta las directrices de contribución para comenzar.