Skip to main content

Get Customer Wallets

Obtenez le solde d’un client dans chaque devise.

Create Ledger Entry

Ajoutez des fonds à un portefeuille ou déduisez-en.

List Ledger Entries

Parcourez toutes les transactions d’un portefeuille, page par page.

Que sont les portefeuilles clients ?

Un portefeuille client contient de l’argent réel pour un client, avec un solde par devise. Utilisez les 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 remboursement sur la carte
  • Accorder des soldes promotionnels, tels que des bonus de bienvenue ou des récompenses de fidélité
  • Appliquer automatiquement les fonds du portefeuille aux frais d’abonnement au moment de la facturation
  • Suivre chaque transaction dans un registre indiquant le solde avant et après
Vous ne créez pas vous-même les portefeuilles. Le portefeuille d’un client pour une devise est créé, avec un solde nul, la première fois que vous ajoutez une entrée au registre dans cette devise. Jusque-là, Get Customer Wallets ne renvoie aucune entrée pour cette devise.
Portefeuilles clients ≠ facturation basée sur des créditsLes portefeuilles clients contiennent de l’argent réel que Dodo Payments applique aux frais d’abonnement.Pour suivre des unités d’utilisation virtuelles telles que les appels d’API, les tokens ou les heures de calcul, utilisez plutôt la facturation basée sur les crédits.
Customer Wallets

Fonctionnement

Lorsqu’un abonnement est renouvelé ou qu’un changement de forfait crée des frais, Dodo Payments applique d’abord le solde du portefeuille du client dans cette devise, puis facture le moyen de paiement pour le montant restant. Si le solde ne couvre qu’une partie des frais, le portefeuille paie cette partie.

Configuration automatique

Vous n’avez rien à configurer. Ajoutez une entrée au registre via l’API ou cliquez sur Apply Credit/Debit dans l’onglet Wallets du client dans le dashboard : le portefeuille pour cette devise est alors prêt à l’emploi.

Prise en charge de plusieurs devises

Chaque devise possède son propre solde. Chaque portefeuille de la réponse Get Customer Wallets contient un currency et un balance dans la plus petite unité monétaire, et la réponse ajoute total_balance_usd, qui correspond à la somme de tous les soldes convertis en USD. Les entrées du registre acceptent ces 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)
Les portefeuilles clients contiennent des soldes en USD, EUR et GBP. Le portefeuille natif en INR abandonné décrit dans Payout Structure est votre portefeuille de versement marchand, et non un portefeuille client. L’INR reste également pris en charge comme devise de transaction pour les abonnements UPI, RuPay et par carte indienne.

Utilisation des portefeuilles

Vérifier les soldes des clients

Obtenez le solde d’un client dans chaque devise, par exemple pour confirmer le solde avant un achat ou l’afficher dans votre application.

Get Customer Wallet Balances

Obtenez les soldes du portefeuille d’un client dans toutes les devises.

Ajouter ou déduire des fonds

Ajoutez des fonds, tels qu’un bonus de bienvenue ou un solde de remboursement, ou déduisez des fonds, par exemple pour une imputation manuelle. entry_type, currency et amount sont obligatoires. amount est un entier positif exprimé dans la plus petite unité monétaire. Ajoutez un reason (jusqu’à 500 caractères) pour votre piste d’audit, ainsi qu’un idempotency_key pour éviter les doublons. La réponse contient le portefeuille mis à jour.
entry_type est 'credit' pour ajouter des fonds au portefeuille et 'debit' pour en déduire. Un débit supérieur au solde échoue avec 400.

Create Customer Wallet Ledger Entry

Ajoutez des fonds au portefeuille d’un client ou déduisez-en.

Consulter l’historique des transactions

Répertoriez chaque crédit et débit d’un client, avec une pagination et un filtre currency facultatif. Chaque entrée contient un event_type (payment, payment_reversal, refund, refund_reversal, dispute, dispute_reversal ou merchant_adjustment), le amount, ainsi que le before_balance et le after_balance. Utilisez le registre pour rapprocher les comptes et répondre aux questions des clients.

List Customer Wallet Ledger Entries

Répertoriez toutes les transactions du portefeuille d’un client.

Exemples concrets

Les exemples utilisent le SDK TypeScript. client est un client DodoPayments, créé comme indiqué dans le Guide d’intégration.

Remboursement vers le portefeuille

Pour rembourser un client sous forme de solde de portefeuille plutôt que sur sa carte, ajoutez le montant avec une entrée de crédit. Les fonds restent dans votre entreprise pour le prochain achat du client.
Un crédit au registre ne rembourse pas le paiement d’origine. Lorsque vous remboursez un paiement via l’API Refunds, Dodo Payments reverse automatiquement vers le portefeuille toute partie du paiement qui avait été réglée par celui-ci.

Bonus de bienvenue / solde promotionnel

Accordez un bonus de bienvenue aux nouveaux clients pour les encourager à effectuer leur premier achat.

Paiement d’abonnement depuis le portefeuille

Déduisez des fonds d’un portefeuille pour payer des frais que vous facturez vous-même. Les renouvellements ne nécessitent pas cette étape, car Dodo Payments leur applique automatiquement le solde.

Système de facturation prépayée

Permettez aux clients d’approvisionner leur compte à l’avance et de réduire ce solde au fil du temps. customerId, paymentId et purchaseId sont vos propres identifiants pour le client, le dépôt et l’achat.
1

Add Initial Funds

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

Apply Balance to Purchases

Déduisez le montant du solde à mesure que le client utilise vos services.
3

Monitor Balances

Vérifiez si les fonds d’un client deviennent insuffisants et invitez-le à recharger son compte.

Prise en charge de plusieurs devises

Conservez des soldes distincts pour les clients de différentes régions.
Gérez les fonds en USD pour les clients basés aux États-Unis.
Gérez les fonds en EUR pour les clients basés en Europe.
Gérez les fonds en GBP pour les clients basés au Royaume-Uni.

Bonnes pratiques

Éviter les transactions en double

Transmettez un idempotency_key dérivé de l’événement à l’origine de l’entrée, tel qu’un identifiant de commande ou de paiement, afin qu’une nouvelle tentative ne puisse pas ajouter ou déduire les fonds deux fois. Si vous répétez une requête avec la même clé, Dodo Payments ne crée aucune nouvelle entrée et renvoie le portefeuille actuel.

Vérifier les soldes avant de facturer

Avant de déduire un montant important d’un portefeuille, vérifiez que le solde le couvre.

Prochaines étapes

Les portefeuilles clients ne prennent pas en charge les fonctionnalités suivantes :
  • Expiration du solde : les fonds du portefeuille n’expirent pas.
  • Analyses : il n’existe aucun rapport de dépenses ni aucune tendance des soldes. Utilisez le registre pour créer les vôtres.
  • Webhooks : aucun webhook n’est déclenché lorsqu’un solde est modifié et il n’existe aucune alerte de solde faible. Pour suivre les modifications, répertoriez les entrées du registre.
Commencez par les opérations de financement et de déduction de base, puis automatisez davantage votre workflow de facturation à mesure que votre entreprise se développe.
Dernière modification le 26 septembre 2026