> ## Documentation Index > Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt > Use this file to discover all available pages before exploring further. # 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. Consulte os saldos monetários dos clientes em diferentes moedas. Adicione ou deduza fundos das carteiras dos clientes. 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](/features/credit-based-billing). Carteiras de clientes ## 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: Saldo em dólares americanos (armazenado em centavos) 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. 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. 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. 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. ```javascript theme={null} 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. ```javascript theme={null} 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. ```javascript theme={null} 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. Adicione fundos à carteira do cliente quando ele fizer um depósito. ```javascript theme={null} 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}` }); ``` Deduza o saldo conforme o cliente usa seus serviços ou renova assinaturas. ```javascript theme={null} 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}` }); ``` Verifique se os clientes estão ficando sem fundos para solicitar uma recarga. ```javascript theme={null} 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. Gerencie fundos em USD para clientes nos Estados Unidos. ```javascript theme={null} 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}` }); ``` Gerencie fundos em INR para clientes indianos. ```javascript theme={null} 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. ```javascript theme={null} 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. ```javascript theme={null} 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.