Skip to main content

Get Customer Wallets

Obtenha o saldo de um cliente em cada moeda.

Create Ledger Entry

Adicione fundos à carteira ou deduza fundos dela.

List Ledger Entries

Percorra todas as transações da carteira usando paginação.

O que são carteiras de clientes?

Uma carteira de cliente mantém dinheiro real para um cliente, com um saldo por moeda. Use carteiras para:
  • Armazenar fundos pré-pagos para pagamentos futuros de assinaturas
  • Processar reembolsos como saldo da carteira em vez de reembolsar o cartão
  • Emitir saldos promocionais, como bônus de boas-vindas ou recompensas de fidelidade
  • Aplicar fundos da carteira às cobranças de assinaturas automaticamente no momento do faturamento
  • Acompanhar cada transação em um livro-caixa com o saldo anterior e posterior
Você não cria carteiras por conta própria. A carteira de um cliente para uma moeda é criada, com saldo zero, na primeira vez que você adiciona uma entrada no livro-caixa nessa moeda. Até lá, Get Customer Wallets não retorna uma entrada para essa moeda.
Carteiras de clientes ≠ faturamento baseado em créditosAs Customer Wallets mantêm dinheiro real que o Dodo Payments aplica às cobranças de assinaturas.Para acompanhar unidades de uso virtuais, como chamadas de API, tokens ou horas de computação, use Credit-Based Billing.
Carteiras de clientes

Como funciona

Quando uma assinatura é renovada ou uma alteração de plano cria uma cobrança, o Dodo Payments primeiro aplica o saldo da carteira do cliente nessa moeda e, em seguida, cobra o restante do método de pagamento. Se o saldo cobrir apenas parte da cobrança, a carteira paga essa parte.

Configuração automática

Você não precisa configurar nada. Adicione uma entrada no livro-caixa pela API ou clique em Apply Credit/Debit na aba Wallets do cliente no dashboard, e a carteira para essa moeda estará pronta para uso.

Suporte a várias moedas

Cada moeda tem seu próprio saldo. Cada carteira na resposta de Get Customer Wallets tem um currency e um balance na menor unidade monetária, e a resposta adiciona total_balance_usd, a soma de todos os saldos convertidos para USD. As entradas do livro-caixa aceitam estas moedas:
integer
Saldo em dólares americanos (armazenado em centavos)
integer
Saldo em euros (armazenado em centavos)
integer
Saldo em libras esterlinas (armazenado em pence)
As carteiras de clientes mantêm saldos em USD, EUR e GBP. A carteira nativa em INR descontinuada descrita em Payout Structure é a carteira de pagamentos do comerciante, não uma carteira de cliente. INR também continua sendo compatível como moeda de transação para assinaturas com UPI, RuPay e cartões indianos.

Trabalhando com carteiras

Verificar saldos dos clientes

Obtenha o saldo de um cliente em todas as moedas, por exemplo, para confirmar o saldo antes de uma compra ou exibi-lo no seu aplicativo.

Get Customer Wallet Balances

Obtenha os saldos da carteira de um cliente em todas as moedas.

Adicionar ou deduzir fundos

Adicione fundos, como um bônus de boas-vindas ou um saldo de reembolso, ou deduza fundos, como em uma cobrança manual. entry_type, currency e amount são obrigatórios. amount é um inteiro positivo na menor unidade monetária. Adicione um reason (até 500 caracteres) ao seu registro de auditoria e um idempotency_key para evitar duplicidades. A resposta é a carteira atualizada.
entry_type é 'credit' para adicionar fundos à carteira e 'debit' para subtrair fundos dela. Um débito maior que o saldo falha com 400.

Create Customer Wallet Ledger Entry

Adicione fundos à carteira de um cliente ou deduza fundos dela.

Ver histórico de transações

Liste todos os créditos e débitos de um cliente, com paginação e um filtro currency opcional. Cada entrada tem um event_type (payment, payment_reversal, refund, refund_reversal, dispute, dispute_reversal ou merchant_adjustment), o amount e o before_balance e after_balance. Use o livro-caixa para reconciliar contas e responder às perguntas dos clientes.

List Customer Wallet Ledger Entries

Liste todas as transações da carteira de um cliente.

Exemplos do mundo real

Os exemplos usam o SDK do TypeScript. client é um cliente DodoPayments, criado conforme descrito no Integration Guide.

Reembolso para a carteira

Para reembolsar um cliente como saldo da carteira em vez de devolver o valor ao cartão, adicione o valor com uma entrada de crédito. Os fundos permanecem com sua empresa para a próxima compra do cliente.
Um crédito no livro-caixa não reembolsa o pagamento original. Quando você reembolsa um pagamento pela Refunds API, o Dodo Payments devolve automaticamente à carteira qualquer parte paga por ela.

Bônus de boas-vindas / saldo promocional

Conceda um bônus de boas-vindas a novos clientes para incentivar a primeira compra.

Pagamento de assinatura pela carteira

Deduza fundos de uma carteira para pagar uma cobrança que você mesmo fatura. As renovações não precisam desta etapa, pois o Dodo Payments aplica o saldo a elas automaticamente.

Sistema de faturamento pré-pago

Permita que os clientes financiem suas contas antecipadamente e consumam esse saldo ao longo do tempo. customerId, paymentId e purchaseId são seus próprios identificadores para o cliente, o depósito e a compra.
1

Add Initial Funds

Adicione fundos à carteira do cliente quando ele fizer um depósito.
2

Apply Balance to Purchases

Deduza o saldo à medida que o cliente usar seus serviços.
3

Monitor Balances

Verifique se um cliente está ficando sem fundos e solicite uma recarga.

Suporte a várias moedas

Mantenha saldos separados para clientes de diferentes regiões.
Gerencie fundos em USD para clientes nos EUA.
Gerencie fundos em EUR para clientes na Europa.
Gerencie fundos em GBP para clientes no Reino Unido.

Práticas recomendadas

Evite transações duplicadas

Transmita um idempotency_key derivado do evento que causou a entrada, como um ID de pedido ou pagamento, para que uma nova tentativa não adicione nem deduza os fundos duas vezes. Se você repetir uma solicitação com a mesma chave, o Dodo Payments não criará uma nova entrada e retornará a carteira atual.

Verifique os saldos antes de cobrar

Antes de deduzir um valor alto de uma carteira, confirme se o saldo é suficiente para cobri-lo.

O que vem a seguir

As carteiras de clientes não são compatíveis com estes recursos:
  • Expiração do saldo: os fundos da carteira não expiram.
  • Analytics: não há relatórios de gastos nem tendências de saldo. Use o livro-caixa para criar os seus próprios.
  • Webhooks: nenhum webhook é acionado quando um saldo muda e não há alertas de saldo baixo. Para acompanhar as alterações, liste as entradas do livro-caixa.
Comece com o provisionamento e a dedução básicos e, à medida que sua empresa crescer, automatize mais etapas do seu fluxo de faturamento.
Última modificação em 26 de setembro de 2026