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.

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 umcurrency 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 filtrocurrency 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.US Customers
US Customers
Gerencie fundos em USD para clientes nos EUA.
European Customers
European Customers
Gerencie fundos em EUR para clientes na Europa.
UK Customers
UK Customers
Gerencie fundos em GBP para clientes no Reino Unido.
Práticas recomendadas
Evite transações duplicadas
Transmita umidempotency_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.