Portafogli Clienti - Dodo Payments Documentation

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.

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.

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:

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

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

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

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:

US Customers

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

Indian Customers

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.

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

​Cosa sono i Portafogli Clienti?

​Come Funziona

​Supporto Multi-Valuta

​Lavorare con i Portafogli

​Controlla i Saldi dei Clienti

Get Customer Wallet Balances

​Aggiungi o Rimuovi Crediti

Create Customer Wallet Ledger Entry

​Visualizza la Cronologia delle Transazioni

List Customer Wallet Ledger Entries

​Esempi del Mondo Reale

​Sistema di Credito API (Come OpenAI)

​Sistema di Fatturazione Prepagata

​Supporto Multi-Valuta

​Migliori Pratiche

​Prevenire Transazioni Duplicati

​Controlla i Saldi Prima di Addebitare

​Cosa Arriverà Dopo

​Controlla i saldi prima di addebitare

​Cosa arriverà dopo

Cosa sono i Portafogli Clienti?

Come Funziona

Supporto Multi-Valuta

Lavorare con i Portafogli

Controlla i Saldi dei Clienti

Aggiungi o Rimuovi Crediti

Visualizza la Cronologia delle Transazioni

Esempi del Mondo Reale

Sistema di Credito API (Come OpenAI)

Sistema di Fatturazione Prepagata

Supporto Multi-Valuta

Migliori Pratiche

Prevenire Transazioni Duplicati

Controlla i Saldi Prima di Addebitare

Cosa Arriverà Dopo

Controlla i saldi prima di addebitare

Cosa arriverà dopo