Billeteras de clientes

Gestiona saldos monetarios prepagados para tus clientes. Añade fondos a las billeteras, aplica saldos a las facturas de suscripciones, gestiona reembolsos como fondos de billetera y consulta el historial de transacciones.

Get Customer Wallets

Consulta los saldos monetarios de los clientes en distintas divisas.

Create Ledger Entry

Añade o deduce fondos de las billeteras de los clientes.

List Ledger Entries

Consulta el historial completo de transacciones con paginación.

​

¿Qué son las billeteras de clientes?

Las billeteras de clientes son cuentas de saldo monetario que almacenan fondos reales para tus usuarios. Cada cliente obtiene una automáticamente cuando creas su cuenta. Puedes usar estas billeteras para:

• Almacenar fondos prepagados para futuros pagos de suscripciones
• Gestionar reembolsos como saldo de billetera en lugar de reembolsos a la tarjeta
• Emitir saldos promocionales como bonos de bienvenida o recompensas de fidelidad
• Aplicar fondos de la billetera a las facturas automáticamente durante la facturación
• Registrar transacciones monetarias con un historial detallado del libro mayor

Cada cliente obtiene automáticamente una billetera cuando creas su cuenta. Las billeteras admiten las divisas USD e INR, con saldos monetarios independientes para cada una.

Billeteras de clientes ≠ facturación basada en créditos

Las billeteras de clientes contienen saldos monetarios reales (USD, INR) que se pueden aplicar a facturas y pagos de suscripciones.

Si quieres realizar un seguimiento de unidades de uso virtuales (llamadas a la API, tokens, horas de cómputo), consulta Facturación basada en créditos.

​

Cómo funciona

Las billeteras de clientes almacenan fondos que los clientes pueden aplicar a sus compras. Cuando un cliente tiene una factura o un cargo recurrente de suscripción, primero se comprueba el saldo de su billetera. Los fondos disponibles se aplican automáticamente a la factura antes de realizar el cargo en su método de pago principal.

​

Configuración automática

Cuando creas un cliente nuevo, Dodo Payments crea automáticamente una billetera con saldo cero. Está lista para recibir fondos de inmediato a través de nuestra API.

​

Compatibilidad con varias divisas

Cada billetera puede contener saldos en distintas divisas:

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 e INR. Próximamente habrá más divisas.

​

Trabajo con billeteras

​

Consulta los saldos de los clientes

Consulta cuánto dinero tiene un cliente en todas las divisas. Esto resulta útil para verificar el saldo disponible antes de procesar una compra o mostrar el saldo en la interfaz de usuario de tu aplicación.

Get Customer Wallet Balances

Consulta los saldos monetarios de la billetera de un cliente en todas las divisas compatibles.

​

Añadir o deducir fondos

Añade fondos a las billeteras de los clientes (como bonos de bienvenida o saldos de reembolso) o deduce fondos (como cargos de suscripción). Puedes indicar los motivos de cada transacción para mantener un registro de auditoría claro.

El campo entry_type utiliza 'credit' para añadir fondos a la billetera y 'debit' para restar fondos de la billetera.

Create Customer Wallet Ledger Entry

Añade o deduce fondos de la billetera de un cliente.

​

Consulta el historial de transacciones

Consulta cada transacción de crédito y débito de un cliente. Este libro mayor detallado te ayuda a conciliar las cuentas y ofrece transparencia a tus clientes.

List Customer Wallet Ledger Entries

Consulta cada transacción monetaria de un cliente.

​

Ejemplos del mundo real

​

Reembolso a la billetera

Cuando un cliente solicita un reembolso, puedes añadir el importe al saldo de su billetera en lugar de realizar un reembolso tradicional a la tarjeta. Así, los fondos permanecen dentro de tu ecosistema para futuras compras.

async function refundToWallet(customerId, refundAmount, originalPaymentId) {
  await client.customers.wallets.ledgerEntries.create(customerId, {
    amount: refundAmount, // Amount in cents
    currency: 'USD',
    entry_type: 'credit',
    reason: `Refund for payment ${originalPaymentId}`,
    idempotency_key: `refund_${originalPaymentId}`
  });
}

​

Bono de bienvenida / saldo promocional

Ofrece a los nuevos clientes un bono monetario de bienvenida para fomentar su primera compra.

async function addWelcomeBonus(customerId) {
  await client.customers.wallets.ledgerEntries.create(customerId, {
    amount: 1000, // $10.00 promotional balance
    currency: 'USD',
    entry_type: 'credit',
    reason: 'Welcome bonus - $10 promotional balance',
    idempotency_key: `welcome_${customerId}`
  });
}

​

Pago de suscripción desde la billetera

Deduce fondos de una billetera para cubrir un cargo de suscripción o una compra manual.

async function deductForPurchase(customerId, purchaseAmount, purchaseId) {
  try {
    await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: purchaseAmount,
      currency: 'USD',
      entry_type: 'debit',
      reason: `Subscription charge - monthly billing`,
      idempotency_key: `charge_${purchaseId}`
    });
  } catch (error) {
    if (error.status === 400) {
      console.log('Insufficient wallet balance');
    }
  }
}

​

Sistema de facturación prepagada

Permite que los clientes financien sus cuentas por adelantado y consuman ese saldo con el tiempo.

1. Add Initial Funds

   Añade fondos a la billetera del cliente cuando realice un depósito.

   await client.customers.wallets.ledgerEntries.create(customerId, {
     amount: 5000, // $50.00 deposit
     currency: 'USD',
     entry_type: 'credit',
     reason: 'Account funding - prepaid deposit',
     idempotency_key: `deposit_${paymentId}`
   });
   
2. Apply Balance to Purchases

   Deducen del saldo a medida que el cliente utiliza tus servicios o renueva sus suscripciones.

   await client.customers.wallets.ledgerEntries.create(customerId, {
     amount: 1500, // $15.00 charge
     currency: 'USD', 
     entry_type: 'debit',
     reason: 'Service purchase - monthly subscription',
     idempotency_key: `purchase_${purchaseId}`
   });
   
3. Monitor Balances

   Comprueba si a los clientes les quedan pocos fondos para solicitarles una recarga.

   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.00
     // Send low balance notification
     await sendLowBalanceNotification(customerId, balance);
   }
   

​

Compatibilidad con varias divisas

Gestiona saldos monetarios independientes para clientes de distintas regiones.

US Customers

Gestiona fondos en USD para clientes ubicados en EE. UU.

await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 20000, // $200.00 in cents
  currency: 'USD',
  entry_type: 'credit',
  reason: 'USD account funding',
  idempotency_key: `usd_deposit_${paymentId}`
});

Indian Customers

Gestiona fondos en INR para clientes indios.

await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 1500000, // Rs 15,000 in paise
  currency: 'INR',
  entry_type: 'credit',
  reason: 'INR account funding',
  idempotency_key: `inr_deposit_${paymentId}`
});

​

Prácticas recomendadas

​

Evita transacciones duplicadas

Utiliza claves de idempotencia para asegurarte de no añadir ni deducir fondos dos veces accidentalmente para el mismo evento.

async function addFundsSafely(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 === 409) {
      // Transaction already processed
      return { success: true, wallet: null, duplicate: true };
    }
    
    throw error;
  }
}

​

Comprueba los saldos antes de realizar cargos

Verifica que los clientes tengan fondos suficientes antes de intentar procesar transacciones grandes desde la billetera.

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('Insufficient funds for this operation');
  }
  
  return usdWallet.balance;
}

​

Próximas novedades

Estas funciones están previstas para futuras versiones:

• Caducidad del saldo: Configura la caducidad de los fondos después de un periodo determinado
• Mejores análisis: Informes detallados de gastos y tendencias de saldo
• Más webhooks: Notificaciones en tiempo real sobre cambios de saldo y alertas de saldo bajo

Comienza con operaciones básicas de adición y deducción de fondos, y después integra flujos de trabajo de facturación automatizados más complejos a medida que crezca tu negocio.