Saltar al contenido principal

Obtener Bolsillos de Clientes

Verifica los saldos de los bolsillos de los clientes en diferentes monedas.

Crear Entrada de Libro Mayor

Agregar o quitar créditos de los bolsillos de los clientes.

Listar Entradas de Libro Mayor

Ver el historial completo de transacciones con paginación.

​
¿Qué son los Bolsillos de Clientes?

Piensa en los bolsillos de clientes como alcancías digitales para tus usuarios. Cada cliente obtiene uno automáticamente cuando creas su cuenta. Puedes usar estos bolsillos para:
  • Rastrear saldos de crédito en USD e INR
  • Construir sistemas de crédito API como OpenAI o Claude
  • Crear facturación prepaga donde los clientes compran créditos por adelantado
  • Manejar reembolsos como créditos en el bolsillo en lugar de efectivo
  • Gestionar facturación compleja con un historial de transacciones detallado
Cada cliente obtiene automáticamente un bolsillo cuando creas su cuenta. Los bolsillos soportan monedas USD e INR con saldos separados para cada uno.
Bolsillos de Clientes

​
¿Cómo Funciona?

Los bolsillos de clientes son simples: contienen dinero (créditos) que los clientes pueden gastar en tus servicios. Cuando un cliente realiza una compra, primero se verifica el saldo de su bolsillo, y se utilizan los créditos disponibles antes de cargar su método de pago.

​
Configuración Automática

Cuando creas un nuevo cliente, Dodo Payments crea automáticamente un bolsillo con saldo cero. Está listo para usar de inmediato a través de nuestra API.

​
Soporte Multimoneda

Cada bolsillo puede contener saldos en diferentes monedas:
​
USD Balance
integer
Saldo en Dólares Estadounidenses (almacenado en centavos)
​
INR Balance
integer
Saldo en Rupias Indias (almacenado en paise)
Actualmente, solo están disponibles los saldos en USD y INR. Más monedas llegarán pronto.

​
Trabajando con Bolsillos

​
Verificar Saldos de Clientes

Ver cuánto crédito tiene un cliente en todas las monedas. Perfecto para verificar si tienen suficientes fondos antes de procesar una compra.

Obtener Saldos de Bolsillos de Clientes

Verifica los saldos de crédito del bolsillo de un cliente en todas las monedas soportadas.

​
Agregar o Quitar Créditos

Otorga créditos a los clientes (como bonos de bienvenida) o deduce créditos (como cargos por uso). Puedes agregar razones para cada transacción para llevar un seguimiento de lo que sucedió.

Crear Entrada de Libro Mayor de Bolsillo de Cliente

Agregar o quitar créditos del bolsillo de un cliente.

​
Ver Historial de Transacciones

Ver cada transacción de crédito y débito de un cliente. Ideal para depurar problemas de facturación o mostrar a los clientes su historial de gastos.

Listar Entradas de Libro Mayor de Bolsillo de Cliente

Ver cada transacción de crédito y débito de un cliente.

​
Ejemplos del Mundo Real

​
Sistema de Créditos API (Como OpenAI)

Construye un sistema donde los clientes compran créditos y los gastan en llamadas a la API: 
// Give new customers welcome credits
async function giveWelcomeCredits(customerId) {
  await client.customers.wallets.ledgerEntries.create(customerId, {
    amount: 10000, // $100 in cents
    currency: 'USD',
    entry_type: 'credit',
    reason: 'Welcome bonus - 100 API credits',
    idempotency_key: `welcome_${customerId}_${Date.now()}`
  });
}

// Charge customers for API usage
async function chargeForApiUsage(customerId, usageCost) {
  try {
    await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: usageCost, // Cost in cents
      currency: 'USD',
      entry_type: 'debit',
      reason: `API usage - ${usageCost} credits consumed`,
      idempotency_key: `usage_${customerId}_${Date.now()}`
    });
  } catch (error) {
    if (error.status === 400) {
      console.log('Customer needs to buy more credits');
    }
  }
}

​
Sistema de Facturación Prepaga

Permite a los clientes comprar créditos por adelantado y gastarlos con el tiempo:
1

Dar la Bienvenida a Nuevos Clientes

Otorga a los nuevos clientes algunos créditos gratuitos para comenzar.
await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 5000, // $50 welcome bonus
  currency: 'USD',
  entry_type: 'credit',
  reason: 'Welcome bonus for new customer',
  idempotency_key: `welcome_${customerId}`
});
2

Manejar Compras de Créditos

Cuando los clientes compran créditos, agrégales a su bolsillo.
await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: purchaseAmount, // Amount paid in cents
  currency: 'USD',
  entry_type: 'credit',
  reason: `Credit purchase - ${purchaseAmount} credits`,
  idempotency_key: `purchase_${paymentId}`
});
3

Cargar por Uso

Deduce créditos cuando los clientes usan tu servicio.
await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: usageCost,
  currency: 'USD', 
  entry_type: 'debit',
  reason: `Service usage - ${usageCost} credits`,
  idempotency_key: `usage_${usageId}`
});
4

Monitorear Saldos

Verifica si los clientes están quedándose sin créditos.
const wallets = await client.customers.wallets.list(customerId);
const usdWallet = wallets.items.find(w => w.currency === 'USD');
const balance = usdWallet.balance;

if (balance < 1000) { // Less than $10
  // Send low balance notification
  await sendLowBalanceNotification(customerId, balance);
}

​
Soporte Multimoneda

Maneja clientes en diferentes países:
Otorga créditos en USD a los clientes con sede en EE. UU..
await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 20000, // $200 in cents
  currency: 'USD',
  entry_type: 'credit',
  reason: 'USD credit purchase',
  idempotency_key: `usd_purchase_${paymentId}`
});
Otorga créditos en INR a los clientes indios.
await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 1500000, // ₹15,000 in paise
  currency: 'INR',
  entry_type: 'credit',
  reason: 'INR credit purchase',
  idempotency_key: `inr_purchase_${paymentId}`
});

​
Mejores Prácticas

​
Prevenir Transacciones Duplicadas

Usa claves de idempotencia para asegurarte de que no cobres accidentalmente a los clientes dos veces por lo mismo: 
async function addCreditsSafely(customerId, amount, reason) {
  const idempotencyKey = `${reason}_${customerId}_${Date.now()}`;
  
  try {
    const result = await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: amount,
      currency: 'USD',
      entry_type: 'credit',
      reason: reason,
      idempotency_key: idempotencyKey
    });
    
    return { success: true, wallet: result };
  } catch (error) {
    if (error.status === 400 && error.message.includes('Insufficient balance')) {
      return { success: false, error: 'INSUFFICIENT_BALANCE' };
    }
    
    if (error.status === 409) {
      // Transaction already processed
      return { success: true, wallet: null, duplicate: true };
    }
    
    throw error;
  }
}

​
Verificar Saldos Antes de Cargar

Siempre verifica que los clientes tengan suficientes créditos antes de procesar operaciones costosas: 
async function checkBalanceBeforeOperation(customerId, requiredAmount) {
  const wallets = await client.customers.wallets.list(customerId);
  const usdWallet = wallets.items.find(w => w.currency === 'USD');
  
  if (!usdWallet || usdWallet.balance < requiredAmount) {
    throw new Error('Not enough credits for this operation');
  }
  
  return usdWallet.balance;
}

​
¿Qué Viene Después?

Estas características están planeadas para futuras versiones:
  • Expiración de Créditos: Establecer créditos para que expiren después de un cierto tiempo
  • Mejores Analíticas: Informes detallados de gastos e información sobre el uso
  • Más Webhooks: Notificaciones en tiempo real para cambios de saldo y créditos bajos
Comienza simple con operaciones básicas de crédito/débito, luego agrega características más complejas a medida que tu negocio crece.