> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Consulta los saldos monetarios de los clientes en distintas divisas.
Añade o deduce fondos de las billeteras de los clientes.
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](/features/credit-based-billing).
## 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:
Saldo en dólares estadounidenses (almacenado en centavos)
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.
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.
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.
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.
```javascript theme={null}
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.
```javascript theme={null}
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.
```javascript theme={null}
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.
Añade fondos a la billetera del cliente cuando realice un depósito.
```javascript theme={null}
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}`
});
```
Deducen del saldo a medida que el cliente utiliza tus servicios o renueva sus suscripciones.
```javascript theme={null}
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}`
});
```
Comprueba si a los clientes les quedan pocos fondos para solicitarles una recarga.
```javascript theme={null}
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.
Gestiona fondos en USD para clientes ubicados en EE. UU.
```javascript theme={null}
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}`
});
```
Gestiona fondos en INR para clientes indios.
```javascript theme={null}
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.
```javascript theme={null}
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.
```javascript theme={null}
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.