Vai al contenuto principale

Ottieni Portafogli Clienti

Controlla i saldi dei portafogli clienti in diverse valute.

Crea Voce di Libro Mastro

Aggiungi o rimuovi crediti dai portafogli clienti.

Elenca Voci di Libro Mastro

Visualizza la cronologia completa delle transazioni con 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 loro account. I portafogli supportano le valute USD e INR con saldi separati per ciascuna.
Portafogli 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 saldi in USD e INR. Altre valute in arrivo presto.

​
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.

Ottieni Saldi dei Portafogli Clienti

Controlla i saldi di credito 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.

Crea Voce di Libro Mastro Portafoglio Cliente

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.

Elenca Voci di Libro Mastro Portafoglio Cliente

Visualizza ogni transazione di credito 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

Dai il Benvenuto ai Nuovi Clienti

Dai ai nuovi clienti alcuni 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

Gestisci gli Acquisti di Crediti

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

Addebita per l'Uso

Deduci 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

Monitora i Saldi

Controlla 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:
Dai 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}`
});
Dai 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 pianificate per future versioni:
  • 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 semplice con operazioni di credito/debito di base, poi aggiungi funzionalità più complesse man mano che la tua attività cresce.