Billeteras de clientes

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 monedas USD, EUR y GBP, con saldos monetarios independientes para cada una.

Billeteras de clientes ≠ facturación basada en créditosLas billeteras de los clientes contienen saldos monetarios reales (USD, EUR, GBP) que pueden aplicarse 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:

integer

Saldo en dólares estadounidenses (almacenado en centavos)

integer

Saldo en euros (almacenado en céntimos)

integer

Saldo en libras esterlinas (almacenado en peniques)

Actualmente, solo están disponibles los saldos en USD, EUR y GBP. La billetera nativa en INR ha sido descontinuada; consulta Estructura de pagos. INR sigue siendo compatible como moneda de transacción para suscripciones de UPI, RuPay y tarjetas de la India.

Trabajo con billeteras

Consultar saldos de clientes

Consulta cuánto dinero tiene un cliente en todas las monedas. 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 monedas compatibles.

Añadir o deducir fondos

Añade fondos a las billeteras de los clientes (como bonificaciones de bienvenida o saldos de reembolsos) o deduce fondos (como cargos de suscripción). Puedes proporcionar motivos para cada transacción a fin de 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.

Consultar el historial de transacciones

Consulta todas las transacciones de crédito y débito de un cliente. Este registro detallado te ayuda a conciliar las cuentas y ofrece transparencia a tus clientes.

List Customer Wallet Ledger Entries

Consulta todas las transacciones monetarias 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. Esto mantiene los fondos 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}`
  });
}

Bonificación de bienvenida / Saldo promocional

Ofrece a los nuevos clientes una bonificación monetaria de bienvenida para incentivar 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 prepago

Permite que los clientes financien sus cuentas por adelantado y utilicen ese saldo progresivamente.

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}`
});

Apply Balance to Purchases

Deduce el 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}`
});

Monitor Balances

Comprueba si los clientes se están quedando sin fondos para solicitarles que realicen 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 monedas

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}`
});

European Customers

Gestiona fondos en EUR para clientes ubicados en Europa.

await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 18000, // €180.00 in cents
  currency: 'EUR',
  entry_type: 'credit',
  reason: 'EUR account funding',
  idempotency_key: `eur_deposit_${paymentId}`
});

UK Customers

Gestiona fondos en GBP para clientes ubicados en el Reino Unido.

await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 15000, // £150.00 in pence
  currency: 'GBP',
  entry_type: 'credit',
  reason: 'GBP account funding',
  idempotency_key: `gbp_deposit_${paymentId}`
});

Prácticas recomendadas

Evitar transacciones duplicadas

Utiliza claves de idempotencia para asegurarte de no añadir ni deducir fondos accidentalmente dos veces 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
    });
    
    // Replaying the same idempotency_key returns the original entry rather than
    // creating a duplicate, so no special duplicate handling is required.
    return { success: true, wallet: result };
  } catch (error) {
    if (error.status === 400) {
      // e.g. insufficient balance on a debit
      return { success: false, reason: 'insufficient_balance' };
    }

    throw error;
  }
}

Comprobar 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 planificadas para futuras versiones:

Caducidad del saldo: Configura los fondos para que caduquen después de un período determinado
Mejores análisis: Informes detallados de gastos y tendencias de los saldos
Más Webhooks: Notificaciones en tiempo real sobre cambios en los saldos y alertas de saldo bajo

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

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

¿Qué son las billeteras de clientes?

Cómo funciona

Configuración automática

Compatibilidad con varias divisas

Trabajo con billeteras

Consultar saldos de clientes

Get Customer Wallet Balances

Añadir o deducir fondos

Create Customer Wallet Ledger Entry

Consultar el historial de transacciones

List Customer Wallet Ledger Entries

Ejemplos del mundo real

Reembolso a la billetera

Bonificación de bienvenida / Saldo promocional

Pago de suscripción desde la billetera

Sistema de facturación prepago

Compatibilidad con varias monedas

Prácticas recomendadas

Evitar transacciones duplicadas

Comprobar los saldos antes de realizar cargos

Próximas novedades

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

​¿Qué son las billeteras de clientes?

​Cómo funciona

​Configuración automática

​Compatibilidad con varias divisas

​Trabajo con billeteras

​Consultar saldos de clientes

Get Customer Wallet Balances

​Añadir o deducir fondos

Create Customer Wallet Ledger Entry

​Consultar el historial de transacciones

List Customer Wallet Ledger Entries

​Ejemplos del mundo real

​Reembolso a la billetera

​Bonificación de bienvenida / Saldo promocional

​Pago de suscripción desde la billetera

​Sistema de facturación prepago

​Compatibilidad con varias monedas

​Prácticas recomendadas

​Evitar transacciones duplicadas

​Comprobar los saldos antes de realizar cargos

​Próximas novedades

¿Qué son las billeteras de clientes?

Cómo funciona

Configuración automática

Compatibilidad con varias divisas

Trabajo con billeteras

Consultar saldos de clientes

Añadir o deducir fondos

Consultar el historial de transacciones

Ejemplos del mundo real

Reembolso a la billetera

Bonificación de bienvenida / Saldo promocional

Pago de suscripción desde la billetera

Sistema de facturación prepago

Compatibilidad con varias monedas

Prácticas recomendadas

Evitar transacciones duplicadas

Comprobar los saldos antes de realizar cargos

Próximas novedades