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 el administrador de paquetes de tu preferencia: 
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 guarda tus claves API de forma segura utilizando variables de entorno. Nunca las comites en el control de versiones ni las expongas en código del lado del cliente.

​
Características Principales

TypeScript First

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

Auto-Pagination

La paginación automática para respuestas de listas facilita el trabajo con conjuntos de datos extensos

Error Handling

Tipos de errores integrados con mensajes detallados para distintos escenarios de fallos

Smart Retries

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: 1 }] },
  { 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: 1 }] },
  { maxRetries: 5 },
);
El SDK vuelve a intentar 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: 'customer@example.com',
  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 event_id únicos para idempotencia. Los IDs duplicados dentro de la misma solicitud son rechazados, y las solicitudes subsiguientes 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' - Mostrar mensajes de depuración, información, advertencias y errores
  • 'info' - Mostrar mensajes de información, advertencias y errores
  • 'warn' - Mostrar advertencias y errores (predeterminado)
  • 'error' - Mostrar solo errores
  • 'off' - Desactivar todos los registros
En el nivel de depuración se registran todas las solicitudes y respuestas HTTP, incluidos encabezados y cuerpos. Algunas cabeceras de autenticación se eliminan, pero los datos sensibles en los cuerpos aún pueden ser 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:

View Migration Guide

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

​
Auto-Paginación

Los métodos de lista en la API de DodoPayments están paginados. Puedes usar la sintaxis for await … of para iterar a través de los elementos de todas las páginas: 
async function fetchAllPayments() {
  const allPayments = [];
  // Automatically fetches more pages as needed.
  for await (const paymentListResponse of client.payments.list()) {
    allPayments.push(paymentListResponse);
  }
  return allPayments;
}
Alternativamente, puedes solicitar una sola página a la vez: 
let page = await client.payments.list();
for (const paymentListResponse of page.items) {
  console.log(paymentListResponse);
}

// Convenience methods are provided for manually paginating:
while (page.hasNextPage()) {
  page = await page.getNextPage();
  // ...
}

​
Requisitos

Los siguientes entornos de ejecución son compatibles:
  • Navegadores web (Chrome actualizado, Firefox, Safari, Edge y más)
  • Node.js 20 LTS o posterior (non-EOL) versiones
  • Deno v1.28.0 o superior
  • Bun 1.0 o posterior
  • Cloudflare Workers
  • Entorno Edge Runtime de Vercel
  • Jest 28 o superior con el entorno "node"
  • Nitro v2.6 o superior
TypeScript >= 4.9 es compatible.

​
Recursos

GitHub Repository

Consulta el código fuente y contribuye

API Reference

Documentación completa de la API

Discord Community

Obtén ayuda y conéctate con desarrolladores

Report Issues

Reporta errores o solicita funciones

​
Soporte

¿Necesitas ayuda con el SDK de TypeScript?

​
Contribuyendo

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