Portefeuilles clients

Get Customer Wallets

Consultez les soldes monétaires des clients dans différentes devises.

Create Ledger Entry

Ajoutez ou déduisez des fonds des portefeuilles clients.

List Ledger Entries

Consultez l’historique complet des transactions avec pagination.

Que sont les portefeuilles clients ?

Les portefeuilles clients sont des comptes de solde monétaire qui conservent de vrais fonds pour vos utilisateurs. Chaque client en reçoit automatiquement un lorsque vous créez son compte. Vous pouvez utiliser ces portefeuilles pour :

Stocker des fonds prépayés pour de futurs paiements d’abonnement
Gérer les remboursements sous forme de solde de portefeuille plutôt que de remboursements sur carte
Attribuer des soldes promotionnels comme des bonus de bienvenue ou des récompenses de fidélité
Appliquer automatiquement les fonds du portefeuille aux factures lors de la facturation
Suivre les transactions monétaires grâce à un historique détaillé du grand livre

Chaque client reçoit automatiquement un portefeuille lorsque vous créez son compte. Les portefeuilles prennent en charge les devises USD et INR, avec des soldes monétaires distincts pour chacune.

Portefeuilles clients ≠ facturation basée sur des créditsLes portefeuilles clients contiennent de vrais soldes monétaires (USD, INR) qui peuvent être appliqués aux factures et aux paiements d’abonnement.Si vous cherchez à suivre des unités d’utilisation virtuelles (appels API, jetons, heures de calcul), consultez plutôt la facturation basée sur des crédits.

Fonctionnement

Les portefeuilles clients contiennent des fonds que les clients peuvent appliquer à leurs achats. Lorsqu’un client a une facture ou des frais d’abonnement récurrents, le solde de son portefeuille est vérifié en premier. Les fonds disponibles sont automatiquement appliqués à la facture avant de débiter son moyen de paiement principal.

Configuration automatique

Lorsque vous créez un nouveau client, Dodo Payments crée automatiquement un portefeuille avec un solde nul. Il est prêt à recevoir des fonds immédiatement via notre API.

Prise en charge de plusieurs devises

Chaque portefeuille peut contenir des soldes dans différentes devises :

integer

Solde en dollars américains (stocké en cents)

integer

Solde en roupies indiennes (stocké en paises)

Actuellement, seuls les soldes en USD et en INR sont disponibles. D’autres devises seront bientôt proposées.

Utiliser les portefeuilles

Consulter les soldes des clients

Consultez le montant des fonds dont dispose un client dans toutes les devises. Cela est utile pour vérifier le solde disponible avant de traiter un achat ou d’afficher le solde dans l’interface utilisateur de votre application.

Get Customer Wallet Balances

Consultez les soldes monétaires du portefeuille d’un client dans toutes les devises prises en charge.

Ajouter ou déduire des fonds

Approvisionnez les portefeuilles clients (par exemple avec des bonus de bienvenue ou des soldes de remboursement) ou déduisez-en des fonds (par exemple pour des frais d’abonnement). Vous pouvez indiquer le motif de chaque transaction afin de conserver une piste d’audit claire.

Le champ entry_type utilise 'credit' pour ajouter des fonds au portefeuille et 'debit' pour en soustraire.

Create Customer Wallet Ledger Entry

Ajoutez ou déduisez des fonds du portefeuille d’un client.

Consulter l’historique des transactions

Consultez chaque transaction de crédit et de débit d’un client. Ce grand livre détaillé vous aide à rapprocher les comptes et offre davantage de transparence à vos clients.

List Customer Wallet Ledger Entries

Consultez chaque transaction monétaire d’un client.

Exemples concrets

Remboursement vers le portefeuille

Lorsqu’un client demande un remboursement, vous pouvez ajouter le montant au solde de son portefeuille au lieu d’effectuer un remboursement traditionnel sur carte. Les fonds restent ainsi dans votre écosystème pour de futurs achats.

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

Bonus de bienvenue / solde promotionnel

Offrez aux nouveaux clients un bonus de bienvenue monétaire pour les encourager à effectuer leur premier achat.

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

Paiement d’abonnement depuis le portefeuille

Déduisez des fonds d’un portefeuille pour couvrir des frais d’abonnement ou un achat manuel.

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

Système de facturation prépayée

Permettez aux clients d’approvisionner leur compte à l’avance et de puiser progressivement dans ce solde.

Add Initial Funds

Ajoutez des fonds au portefeuille du client lorsqu’il effectue un dépôt.

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

Apply Balance to Purchases

Déduisez du solde lorsque le client utilise vos services ou renouvelle son abonnement.

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

Monitor Balances

Vérifiez si les clients manquent de fonds afin de les inviter à recharger leur compte.

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

Prise en charge de plusieurs devises

Gérez des soldes monétaires distincts pour les clients de différentes régions.

US Customers

Gérez les fonds en USD des clients basés aux États-Unis.

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

Indian Customers

Gérez les fonds en INR des clients indiens.

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

Bonnes pratiques

Éviter les transactions en double

Utilisez des clés d’idempotence pour éviter d’ajouter ou de déduire accidentellement des fonds deux fois pour le même événement.

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

Vérifier les soldes avant le débit

Vérifiez que les clients disposent de fonds suffisants avant de tenter de traiter des transactions importantes depuis le portefeuille.

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

Prochaines évolutions

Ces fonctionnalités sont prévues pour de prochaines versions :

Expiration du solde : définissez une date d’expiration pour les fonds
Analyses améliorées : rapports détaillés sur les dépenses et tendances des soldes
Davantage de Webhooks : notifications en temps réel pour les changements de solde et les alertes de solde faible

Commencez par les opérations de base d’approvisionnement et de déduction, puis intégrez des workflows de facturation automatisés plus complexes à mesure que votre entreprise se développe.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

Que sont les portefeuilles clients ?

Fonctionnement

Configuration automatique

Prise en charge de plusieurs devises

Utiliser les portefeuilles

Consulter les soldes des clients

Get Customer Wallet Balances

Ajouter ou déduire des fonds

Create Customer Wallet Ledger Entry

Consulter l’historique des transactions

List Customer Wallet Ledger Entries

Exemples concrets

Remboursement vers le portefeuille

Bonus de bienvenue / solde promotionnel

Paiement d’abonnement depuis le portefeuille

Système de facturation prépayée

Prise en charge de plusieurs devises

Bonnes pratiques

Éviter les transactions en double

Vérifier les soldes avant le débit

Prochaines évolutions

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

​Que sont les portefeuilles clients ?

​Fonctionnement

​Configuration automatique

​Prise en charge de plusieurs devises

​Utiliser les portefeuilles

​Consulter les soldes des clients

Get Customer Wallet Balances

​Ajouter ou déduire des fonds

Create Customer Wallet Ledger Entry

​Consulter l’historique des transactions

List Customer Wallet Ledger Entries

​Exemples concrets

​Remboursement vers le portefeuille

​Bonus de bienvenue / solde promotionnel

​Paiement d’abonnement depuis le portefeuille

​Système de facturation prépayée

​Prise en charge de plusieurs devises

​Bonnes pratiques

​Éviter les transactions en double

​Vérifier les soldes avant le débit

​Prochaines évolutions

Que sont les portefeuilles clients ?

Fonctionnement

Configuration automatique

Prise en charge de plusieurs devises

Utiliser les portefeuilles

Consulter les soldes des clients

Ajouter ou déduire des fonds

Consulter l’historique des transactions

Exemples concrets

Remboursement vers le portefeuille

Bonus de bienvenue / solde promotionnel

Paiement d’abonnement depuis le portefeuille

Système de facturation prépayée

Prise en charge de plusieurs devises

Bonnes pratiques

Éviter les transactions en double

Vérifier les soldes avant le débit

Prochaines évolutions