Vai al contenuto principale

Get Customer Wallets

Controlla i saldi del portafoglio cliente in tutte le valute.

Create Ledger Entry

Aggiungi o rimuovi crediti dai portafogli dei clienti.

List Ledger Entries

Visualizza lo storico completo delle transazioni con la paginazione.

​
Cosa sono i Portafogli Clienti?

Pensa ai portafogli clienti come a salvadanai digitali per i tuoi utenti. Ogni cliente ne riceve uno automaticamente quando crei il loro account. Puoi utilizzare questi portafogli per:
  • Tenere traccia dei saldi di credito in USD e INR
  • Costruire sistemi di credito API come OpenAI o Claude
  • Creare fatturazione prepagata in cui i clienti acquistano crediti in anticipo
  • Gestire rimborsi come crediti nel portafoglio invece di contante
  • Gestire fatturazioni complesse con una cronologia dettagliata delle transazioni
Ogni cliente riceve automaticamente un portafoglio quando crei il suo account. I portafogli supportano le valute USD e INR con saldi separati per ciascuna.
Portafogli dei clienti

​
Come Funziona

I portafogli clienti sono semplici: contengono denaro (crediti) che i clienti possono spendere per i tuoi servizi. Quando un cliente effettua un acquisto, il saldo del suo portafoglio viene controllato per primo e i crediti disponibili vengono utilizzati prima di addebitare il metodo di pagamento.

​
Configurazione Automatica

Quando crei un nuovo cliente, Dodo Payments crea automaticamente un portafoglio con saldo zero. È pronto per essere utilizzato immediatamente tramite la nostra API.

​
Supporto Multi-Valuta

Ogni portafoglio può contenere saldi in diverse valute:
​
USD Balance
integer
Saldo in dollari statunitensi (memorizzato in centesimi)
​
INR Balance
integer
Saldo in rupie indiane (memorizzato in paise)
Attualmente sono disponibili solo i saldi in USD e INR. Altre valute in arrivo.

​
Lavorare con i Portafogli

​
Controlla i Saldi dei Clienti

Vedi quanti crediti ha un cliente in tutte le valute. Perfetto per controllare se hanno fondi sufficienti prima di elaborare un acquisto.

Get Customer Wallet Balances

Controlla i saldi dei crediti del portafoglio di un cliente in tutte le valute supportate.

​
Aggiungi o Rimuovi Crediti

Dai ai clienti crediti (come bonus di benvenuto) o deduci crediti (come costi di utilizzo). Puoi aggiungere motivi per ogni transazione per tenere traccia di cosa è successo.

Create Customer Wallet Ledger Entry

Aggiungi o rimuovi crediti dal portafoglio di un cliente.

​
Visualizza la Cronologia delle Transazioni

Vedi ogni transazione di credito e addebito per un cliente. Ottimo per il debug dei problemi di fatturazione o per mostrare ai clienti la loro cronologia di spesa.

List Customer Wallet Ledger Entries

Visualizza ogni transazione di accredito e addebito per un cliente.

​
Esempi del Mondo Reale

​
Sistema di Credito API (Come OpenAI)

Costruisci un sistema in cui i clienti acquistano crediti e li spendono per chiamate API: 
// Give new customers welcome credits
async function giveWelcomeCredits(customerId) {
  await client.customers.wallets.ledgerEntries.create(customerId, {
    amount: 10000, // $100 in cents
    currency: 'USD',
    entry_type: 'credit',
    reason: 'Welcome bonus - 100 API credits',
    idempotency_key: `welcome_${customerId}_${Date.now()}`
  });
}

// Charge customers for API usage
async function chargeForApiUsage(customerId, usageCost) {
  try {
    await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: usageCost, // Cost in cents
      currency: 'USD',
      entry_type: 'debit',
      reason: `API usage - ${usageCost} credits consumed`,
      idempotency_key: `usage_${customerId}_${Date.now()}`
    });
  } catch (error) {
    if (error.status === 400) {
      console.log('Customer needs to buy more credits');
    }
  }
}

​
Sistema di Fatturazione Prepagata

Consenti ai clienti di acquistare crediti in anticipo e spenderli nel tempo:
1

Welcome New Customers

Dai ai nuovi clienti dei crediti gratuiti per iniziare.
await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 5000, // $50 welcome bonus
  currency: 'USD',
  entry_type: 'credit',
  reason: 'Welcome bonus for new customer',
  idempotency_key: `welcome_${customerId}`
});
2

Handle Credit Purchases

Quando i clienti acquistano crediti, aggiungili al loro portafoglio.
await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: purchaseAmount, // Amount paid in cents
  currency: 'USD',
  entry_type: 'credit',
  reason: `Credit purchase - ${purchaseAmount} credits`,
  idempotency_key: `purchase_${paymentId}`
});
3

Charge for Usage

Detrai i crediti quando i clienti utilizzano il tuo servizio.
await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: usageCost,
  currency: 'USD', 
  entry_type: 'debit',
  reason: `Service usage - ${usageCost} credits`,
  idempotency_key: `usage_${usageId}`
});
4

Monitor Balances

Verifica se i clienti stanno esaurendo i crediti.
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
  // Send low balance notification
  await sendLowBalanceNotification(customerId, balance);
}

​
Supporto Multi-Valuta

Gestisci clienti in diversi paesi:
Attribuisci crediti in USD ai clienti con sede negli Stati Uniti.
await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 20000, // $200 in cents
  currency: 'USD',
  entry_type: 'credit',
  reason: 'USD credit purchase',
  idempotency_key: `usd_purchase_${paymentId}`
});
Attribuisci crediti in INR ai clienti indiani.
await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 1500000, // Rs 15,000 in paise
  currency: 'INR',
  entry_type: 'credit',
  reason: 'INR credit purchase',
  idempotency_key: `inr_purchase_${paymentId}`
});

​
Migliori Pratiche

​
Prevenire Transazioni Duplicati

Usa chiavi di idempotenza per assicurarti di non addebitare accidentalmente i clienti due volte per la stessa cosa: 
async function addCreditsSafely(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 === 400 && error.message.includes('Insufficient balance')) {
      return { success: false, error: 'INSUFFICIENT_BALANCE' };
    }
    
    if (error.status === 409) {
      // Transaction already processed
      return { success: true, wallet: null, duplicate: true };
    }
    
    throw error;
  }
}

​
Controlla i Saldi Prima di Addebitare

Verifica sempre che i clienti abbiano crediti sufficienti prima di elaborare operazioni costose: 
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('Not enough credits for this operation');
  }
  
  return usdWallet.balance;
}

​
Cosa Arriverà Dopo

Queste funzionalità sono previste per le versioni future:
  • Scadenza dei Crediti: Imposta i crediti per scadere dopo un certo periodo
  • Migliori Analisi: Rapporti dettagliati sulle spese e approfondimenti sull’uso
  • Più Webhook: Notifiche in tempo reale per cambiamenti di saldo e crediti bassi
Inizia in modo semplice con operazioni di accredito/addebito di base, quindi aggiungi funzionalità più complesse man mano che la tua azienda cresce.

​
Controlla i saldi prima di addebitare

Verifica che i clienti abbiano fondi sufficienti prima di tentare di elaborare transazioni importanti dal portafoglio. 
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;
}

​
Cosa arriverà dopo

Queste funzionalità sono previste per versioni future:
  • Scadenza del saldo: Imposta la scadenza dei fondi dopo un certo periodo
  • Analisi migliorate: Report dettagliati sulle spese e tendenze del saldo
  • Altri webhook: Notifiche in tempo reale per le variazioni del saldo e gli avvisi di saldo basso
Inizia con operazioni di finanziamento e deduzione di base, quindi integra flussi di lavoro di fatturazione automatizzata più complessi man mano che la tua attività cresce.
Last modified on March 3, 2026