Carteiras de clientes

Gerencie saldos monetários pré-pagos para seus clientes. Adicione fundos às carteiras, aplique saldos a faturas de assinaturas, processe reembolsos como fundos da carteira e acompanhe o histórico de transações.

Get Customer Wallets

Consulte os saldos monetários dos clientes em diferentes moedas.

Create Ledger Entry

Adicione ou deduza fundos das carteiras dos clientes.

List Ledger Entries

Consulte o histórico completo de transações com paginação.

​

O que são carteiras de clientes?

As carteiras de clientes são contas de saldo monetário que mantêm fundos reais para seus usuários. Cada cliente recebe uma automaticamente quando você cria sua conta. Você pode usar essas carteiras para:

• Armazenar fundos pré-pagos para futuros pagamentos de assinaturas
• Processar reembolsos como saldo da carteira em vez de reembolsos no cartão
• Emitir saldos promocionais como bônus de boas-vindas ou recompensas de fidelidade
• Aplicar fundos da carteira às faturas automaticamente durante o faturamento
• Acompanhar transações monetárias com um histórico detalhado no livro-razão

Cada cliente recebe automaticamente uma carteira quando você cria sua conta. As carteiras são compatíveis com as moedas USD e INR, com saldos monetários separados para cada uma.

Carteiras de clientes ≠ faturamento baseado em créditos

As carteiras de clientes mantêm saldos monetários reais (USD, INR) que podem ser aplicados a faturas e pagamentos de assinaturas.

Se você quer acompanhar unidades de uso virtuais (chamadas de API, tokens, horas de computação), consulte Faturamento baseado em créditos.

​

Como funciona

As carteiras de clientes mantêm fundos que os clientes podem aplicar em suas compras. Quando um cliente tem uma fatura ou uma cobrança recorrente de assinatura, o saldo da carteira é verificado primeiro. Todos os fundos disponíveis são aplicados automaticamente à fatura antes da cobrança do método de pagamento principal.

​

Configuração automática

Quando você cria um novo cliente, Dodo Payments cria automaticamente uma carteira com saldo zero. Ela está pronta para receber fundos imediatamente por meio da nossa API.

​

Suporte a várias moedas

Cada carteira pode manter saldos em diferentes moedas:

USD Balance · integer

Saldo em dólares americanos (armazenado em centavos)

INR Balance · integer

Saldo em rúpias indianas (armazenado em paise)

Atualmente, apenas os saldos em USD e INR estão disponíveis. Em breve, teremos mais moedas.

​

Trabalhando com carteiras

​

Consultar saldos dos clientes

Veja quanto um cliente tem em fundos em todas as moedas. Isso é útil para verificar o saldo disponível antes de processar uma compra ou exibir o saldo na interface do usuário da sua aplicação.

Get Customer Wallet Balances

Consulte os saldos monetários da carteira de um cliente em todas as moedas compatíveis.

​

Adicionar ou deduzir fundos

Adicione fundos às carteiras dos clientes (como bônus de boas-vindas ou saldos de reembolso) ou deduza fundos (como cobranças de assinaturas). Você pode informar os motivos de cada transação para manter um registro de auditoria claro.

O campo entry_type usa 'credit' para adicionar fundos à carteira e 'debit' para subtrair fundos da carteira.

Create Customer Wallet Ledger Entry

Adicione ou deduza fundos da carteira de um cliente.

​

Consultar o histórico de transações

Veja todas as transações de crédito e débito de um cliente. Esse livro-razão detalhado ajuda a reconciliar contas e oferece transparência aos seus clientes.

List Customer Wallet Ledger Entries

Consulte todas as transações monetárias de um cliente.

​

Exemplos do mundo real

​

Reembolso para a carteira

Quando um cliente solicita um reembolso, você pode adicionar o valor ao saldo da carteira dele em vez de realizar um reembolso tradicional no cartão. Isso mantém os fundos no seu ecossistema para compras futuras.

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

​

Bônus de boas-vindas / saldo promocional

Ofereça aos novos clientes um bônus monetário de boas-vindas para incentivar a primeira 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}`
  });
}

​

Pagamento de assinatura usando a carteira

Deduza fundos de uma carteira para cobrir uma cobrança de assinatura ou uma 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 faturamento pré-pago

Permita que os clientes financiem suas contas antecipadamente e consumam esse saldo ao longo do tempo.

1. Add Initial Funds

   Adicione fundos à carteira do cliente quando ele fizer um 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

   Deduza o saldo conforme o cliente usa seus serviços ou renova assinaturas.

   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

   Verifique se os clientes estão ficando sem fundos para solicitar uma 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);
   }
   

​

Suporte a várias moedas

Gerencie saldos monetários separados para clientes em diferentes regiões.

US Customers

Gerencie fundos em USD para clientes nos Estados Unidos.

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

Gerencie fundos em INR para clientes indianos.

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áticas recomendadas

​

Evite transações duplicadas

Use chaves de idempotência para garantir que você não adicione ou deduza fundos acidentalmente duas vezes para o mesmo 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;
  }
}

​

Consulte os saldos antes de cobrar

Verifique se os clientes têm fundos suficientes antes de tentar processar grandes transações a partir da carteira.

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

​

O que vem a seguir

Estes recursos estão planejados para versões futuras:

• Expiração de saldo: defina um prazo para a expiração dos fundos
• Melhores análises: relatórios detalhados de gastos e tendências de saldo
• Mais Webhooks: notificações em tempo real sobre alterações de saldo e alertas de saldo baixo

Comece com operações básicas de adição e dedução de fundos e, depois, integre fluxos de trabalho de faturamento automatizado mais complexos à medida que sua empresa crescer.