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, EUR et GBP, avec un solde monétaire distinct pour chacune.

Portefeuilles clients ≠ facturation basée sur des créditsLes portefeuilles clients contiennent des soldes monétaires réels (USD, EUR, GBP) 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 euros (stocké en centimes)

integer

Solde en livres sterling (stocké en pence)

Actuellement, seuls les soldes en USD, EUR et GBP sont disponibles. Le portefeuille natif en INR a été supprimé — consultez Structure des versements. L’INR reste pris en charge comme devise de transaction pour les abonnements UPI, RuPay et par carte en Inde.

Utilisation des portefeuilles

Vérifier 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

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

Ajouter ou déduire des fonds

Créditez les portefeuilles des 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 déduire.

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 registre détaillé vous aide à rapprocher les comptes et assure la transparence pour 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 par 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

Accordez 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 au fil du temps.

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 ses abonnements.

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 commencent à manquer de fonds afin de les inviter à recharger leur solde.

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

European Customers

Gérez les fonds en EUR des clients basés en Europe.

await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 18000, // €180.00 in cents
  currency: 'EUR',
  entry_type: 'credit',
  reason: 'EUR account funding',
  idempotency_key: `eur_deposit_${paymentId}`
});

UK Customers

Gérez les fonds en GBP des clients basés au Royaume-Uni.

await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 15000, // £150.00 in pence
  currency: 'GBP',
  entry_type: 'credit',
  reason: 'GBP account funding',
  idempotency_key: `gbp_deposit_${paymentId}`
});

Bonnes pratiques

Éviter les transactions en double

Utilisez des clés d’idempotence pour vous assurer de ne pas ajouter ou 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
    });
    
    // Replaying the same idempotency_key returns the original entry rather than
    // creating a duplicate, so no special duplicate handling is required.
    return { success: true, wallet: result };
  } catch (error) {
    if (error.status === 400) {
      // e.g. insufficient balance on a debit
      return { success: false, reason: 'insufficient_balance' };
    }

    throw error;
  }
}

Vérifier les soldes avant de facturer

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 étapes

Ces fonctionnalités sont prévues dans 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’ajout et de déduction de fonds, 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

Utilisation des portefeuilles

Vérifier 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 de facturer

Prochaines étapes

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

​Que sont les portefeuilles clients ?

​Fonctionnement

​Configuration automatique

​Prise en charge de plusieurs devises

​Utilisation des portefeuilles

​Vérifier 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 de facturer

​Prochaines étapes

Que sont les portefeuilles clients ?

Fonctionnement

Configuration automatique

Prise en charge de plusieurs devises

Utilisation des portefeuilles

Vérifier 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 de facturer

Prochaines étapes