Billeteras de clientes

Get Customer Wallets

Obtén el saldo de un cliente en cada moneda.

Create Ledger Entry

Añade fondos a una billetera o deduce fondos de ella.

List Ledger Entries

Consulta todas las transacciones de una billetera por páginas.

¿Qué son las billeteras de clientes?

Una billetera de cliente guarda dinero real para un cliente, con un saldo por moneda. Usa las billeteras para:

Almacenar fondos prepagos para futuros pagos de suscripción
Gestionar reembolsos como saldo de la billetera en lugar de devolverlos a la tarjeta
Emitir saldos promocionales, como bonos de bienvenida o recompensas de fidelidad
Aplicar fondos de la billetera a cargos de suscripción automáticamente en el momento de la facturación
Registrar cada transacción en un libro mayor con el saldo anterior y posterior

No creas las billeteras manualmente. La billetera de un cliente para una moneda se crea, con saldo cero, la primera vez que añades una entrada al libro mayor en esa moneda. Hasta entonces, Get Customer Wallets no devuelve ninguna entrada para esa moneda.

Billeteras de clientes ≠ facturación basada en créditosLas billeteras de clientes contienen dinero real que Dodo Payments aplica a los cargos de suscripción.Para registrar unidades de uso virtuales, como llamadas a la API, tokens u horas de cómputo, usa Credit-Based Billing.

Cómo funciona

Cuando una suscripción se renueva o un cambio de plan genera un cargo, Dodo Payments aplica primero el saldo de la billetera del cliente en esa moneda y, después, cobra el resto al método de pago. Si el saldo cubre solo una parte del cargo, la billetera paga esa parte.

Configuración automática

No necesitas configurar nada. Añade una entrada al libro mayor mediante la API o haz clic en Apply Credit/Debit en la pestaña Wallets del cliente en el dashboard, y la billetera para esa moneda estará lista para usarse.

Compatibilidad con varias divisas

Cada moneda tiene su propio saldo. Cada billetera de la respuesta de Get Customer Wallets tiene un currency y un balance en la unidad monetaria más pequeña, y la respuesta añade total_balance_usd, la suma de todos los saldos convertidos a USD. Las entradas del libro mayor aceptan estas monedas:

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)

Las billeteras de clientes contienen saldos en USD, EUR y GBP. La billetera nativa en INR discontinuada que se describe en Payout Structure es tu billetera de pagos al comerciante, no una billetera de cliente. INR también sigue siendo compatible como moneda de transacción para suscripciones con UPI, RuPay y tarjetas de India.

Trabajo con billeteras

Consultar saldos de clientes

Obtén el saldo de un cliente en todas las monedas, por ejemplo, para confirmar el saldo antes de una compra o mostrarlo en tu aplicación.

Get Customer Wallet Balances

Obtén los saldos de las billeteras de un cliente en todas las monedas.

Añadir o deducir fondos

Añade fondos, como un bono de bienvenida o un saldo de reembolso, o deduce fondos, como un cargo manual. entry_type, currency y amount son obligatorios. amount es un entero positivo en la unidad monetaria más pequeña. Añade un reason (de hasta 500 caracteres) para tu registro de auditoría y un idempotency_key para evitar duplicados. La respuesta es la billetera actualizada.

entry_type es 'credit' para añadir fondos a la billetera y 'debit' para restar fondos de ella. Un débito superior al saldo falla con 400.

Create Customer Wallet Ledger Entry

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

Consultar el historial de transacciones

Enumera todos los créditos y débitos de un cliente, con paginación y un filtro opcional currency. Cada entrada tiene un event_type (payment, payment_reversal, refund, refund_reversal, dispute, dispute_reversal o merchant_adjustment), el amount y el before_balance y after_balance. Usa el libro mayor para conciliar las cuentas y responder a las preguntas de los clientes.

List Customer Wallet Ledger Entries

Enumera todas las transacciones de la billetera de un cliente.

Ejemplos del mundo real

Los ejemplos usan el SDK de TypeScript. client es un cliente DodoPayments, creado como se indica en la Integration Guide.

Reembolso a la billetera

Para reembolsar a un cliente como saldo de la billetera en lugar de devolver el dinero a su tarjeta, añade el importe mediante una entrada de crédito. Los fondos permanecen en tu empresa para la próxima compra del cliente.

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

Un crédito del libro mayor no reembolsa el pago original. Cuando reembolsas un pago mediante la API de Refunds, Dodo Payments devuelve automáticamente a la billetera cualquier parte que esta haya pagado.

Bono de bienvenida / saldo promocional

Ofrece a los nuevos clientes un bono 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 pagar un cargo que facturas por tu cuenta. Las renovaciones no necesitan este paso, porque Dodo Payments aplica automáticamente el saldo a ellas.

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

Sistema de facturación prepaga

Permite que los clientes financien su cuenta por adelantado y reduzcan ese saldo con el tiempo. customerId, paymentId y purchaseId son tus propios identificadores para el cliente, el depósito y la compra.

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.

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

Monitor Balances

Comprueba si a un cliente le quedan pocos fondos y solicita una recarga.

const wallets = await client.customers.wallets.list(customerId);
const usdWallet = wallets.items.find(w => w.currency === 'USD');
const balance = usdWallet?.balance ?? 0; // no USD wallet yet means a zero balance

if (balance < 1000) { // Less than $10.00
  // sendLowBalanceNotification is your own function, for example an email
  await sendLowBalanceNotification(customerId, balance);
}

Compatibilidad con varias monedas

Mantén saldos separados para clientes de distintas regiones.

US Customers

Gestiona fondos en USD para clientes con sede 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 con sede 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 con sede 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

Evita transacciones duplicadas

Pasa un idempotency_key derivado del evento que provocó la entrada, como un ID de pedido o pago, para que un reintento no añada ni deduzca los fondos dos veces. Si repites una solicitud con la misma clave, Dodo Payments no crea ninguna entrada nueva y devuelve la billetera actual.

async function addFundsSafely(customerId, amount, reason, eventId) {
  // Derive the key from the event, not from the time, so retries reuse it.
  const idempotencyKey = `credit_${customerId}_${eventId}`;

  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 creates no duplicate entry and
    // returns the wallet, 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;
  }
}

Comprueba los saldos antes de realizar cargos

Antes de deducir un importe grande de una billetera, confirma que el saldo lo cubra.

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

Las billeteras de clientes no admiten estas funciones:

Expiración del saldo: los fondos de la billetera no caducan.
Analytics: no hay informes de gastos ni tendencias de saldo. Usa el libro mayor para crear los tuyos.
Webhooks: no se activa ningún webhook cuando cambia un saldo y no hay alertas de saldo bajo. Para realizar un seguimiento de los cambios, enumera las entradas del libro mayor.

Empieza con la financiación y las deducciones básicas y, después, automatiza una mayor parte de tu flujo de facturación a medida que crezca tu empresa.

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

Bono de bienvenida / saldo promocional

Pago de suscripción desde la billetera

Sistema de facturación prepaga

Compatibilidad con varias monedas

Prácticas recomendadas

Evita transacciones duplicadas

Comprueba 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

​Bono de bienvenida / saldo promocional

​Pago de suscripción desde la billetera

​Sistema de facturación prepaga

​Compatibilidad con varias monedas

​Prácticas recomendadas

​Evita transacciones duplicadas

​Comprueba 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

Bono de bienvenida / saldo promocional

Pago de suscripción desde la billetera

Sistema de facturación prepaga

Compatibilidad con varias monedas

Prácticas recomendadas

Evita transacciones duplicadas

Comprueba los saldos antes de realizar cargos

Próximas novedades