Customer Wallets

Get Customer Wallets

顧客の通貨ごとの金銭残高を確認します。

Create Ledger Entry

顧客のウォレットに資金を追加または差し引きします。

List Ledger Entries

View complete transaction history with pagination.

What are Customer Wallets?

カスタマーウォレットはユーザーの実際の資金を保持する金銭残高アカウントです。顧客のアカウントを作成すると自動的に1つ付与されます。これらのウォレットを次の用途に利用できます：

将来のサブスクリプション支払いのために前払い資金を保管する
払い戻しをカードではなくウォレット残高として処理する
ウェルカムボーナスやロイヤリティ報酬のようなプロモーション残高を発行する
請求時にウォレット資金を自動的に請求書へ適用する
詳細な台帳履歴で金銭取引を追跡する

アカウントを作成すると、すべての顧客に自動的にウォレットが付与されます。ウォレットは USD、EUR、GBP の通貨に対応しており、それぞれ個別の金銭残高を保持します。

カスタマーウォレット ≠ クレジットベース課金顧客ウォレットには、請求書やサブスクリプションの支払いに充当できる実際の金銭残高（USD、EUR、GBP）が保持されます。仮想の使用単位（API コール、トークン、コンピュート時間）を追跡したい場合は、代わりにCredit-Based Billingをご覧ください。

仕組み

カスタマーウォレットには、顧客が購入に適用できる資金が保持されます。顧客に請求書や定期課金が発生すると、最初にウォレット残高が確認されます。利用可能な資金があれば、主要な支払い方法に請求する前に自動的に請求書に適用されます。

自動セットアップ

新しい顧客を作成すると、Dodo Payments は自動で残高ゼロのウォレットを作成します。API ですぐに資金を受け取る準備が整います。

マルチ通貨対応

各ウォレットは異なる通貨で残高を保持できます：

integer

米ドルでの残高（セント単位で保存）

integer

ユーロの残高（セント単位で保存）

integer

英ポンドの残高（ペンス単位で保存）

現在利用できる残高は USD、EUR、GBP のみです。INR ネイティブウォレットは廃止されました。詳しくは Payout Structure を参照してください。INR は、UPI、RuPay、およびインド発行カードのサブスクリプションにおける取引通貨として引き続きサポートされています。

ウォレットの操作

顧客残高の確認

すべての通貨における顧客の保有資金を確認できます。購入を処理する前に利用可能残高を確認したり、アプリケーションの UI に残高を表示したりする際に便利です。

Get Customer Wallet Balances

サポートされているすべての通貨で、顧客のウォレットの金銭残高を確認します。

資金の追加または差し引き

顧客のウォレットに資金を追加したり（ウェルカムボーナスや返金残高など）、資金を差し引いたりできます（サブスクリプション料金など）。各取引の理由を指定できるため、明確な監査証跡を維持できます。

The entry_type field uses 'credit' to add funds to the wallet and 'debit' to subtract funds from the wallet.

Create Customer Wallet Ledger Entry

顧客のウォレットに資金を追加または差し引きします。

取引履歴の表示

顧客のすべての入金および出金取引を確認できます。この詳細な台帳は、アカウントの照合に役立つほか、顧客に透明性を提供します。

List Customer Wallet Ledger Entries

顧客のすべての金銭取引を表示します。

実際の使用例

ウォレットへの返金

顧客から返金を依頼された場合、従来のカード返金を行う代わりに、返金額をウォレット残高に追加できます。これにより、資金を自社のエコシステム内に保持し、今後の購入に利用できます。

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

ウェルカムボーナス／プロモーション残高

新規顧客に金銭的なウェルカムボーナスを付与して、初回購入を促します。

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

ウォレットからのサブスクリプション支払い

ウォレットから資金を差し引いて、サブスクリプション料金や手動購入の支払いに充当します。

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

前払い請求システム

顧客があらかじめアカウントに資金を入金し、その残高を時間の経過とともに使えるようにします。

Add Initial Funds

顧客が入金した際に、顧客のウォレットに資金を追加します。

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

顧客がサービスを利用したりサブスクリプションを更新したりすると、残高から資金を差し引きます。

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

顧客の資金が不足しそうな場合に確認し、チャージを促します。

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

マルチカレンシー対応

地域ごとに顧客の金銭残高を分けて管理します。

US Customers

米国を拠点とする顧客の USD 資金を管理します。

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

欧州を拠点とする顧客の EUR 資金を管理します。

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

英国を拠点とする顧客の GBP 資金を管理します。

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

ベストプラクティス

重複取引を防止する

同じイベントに対して資金を誤って 2 回追加または差し引きしないよう、idempotency keys を使用します。

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

課金前に残高を確認する

ウォレットから大きな取引を処理する前に、顧客に十分な資金があることを確認します。

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

今後の予定

これらの機能は今後のリリースで提供される予定です。

残高の有効期限: 一定期間後に資金の有効期限が切れるよう設定
より充実した分析: 詳細な支出レポートと残高の推移
Webhook の拡充: 残高の変更や残高不足に関するリアルタイム通知

基本的な資金の追加・差し引き操作から始め、ビジネスの成長に合わせて、より複雑な自動請求ワークフローを統合してください。

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

What are Customer Wallets?

仕組み

自動セットアップ

マルチ通貨対応

ウォレットの操作

顧客残高の確認

Get Customer Wallet Balances

資金の追加または差し引き

Create Customer Wallet Ledger Entry

取引履歴の表示

List Customer Wallet Ledger Entries

実際の使用例

ウォレットへの返金

ウェルカムボーナス／プロモーション残高

ウォレットからのサブスクリプション支払い

前払い請求システム

マルチカレンシー対応

ベストプラクティス

重複取引を防止する

課金前に残高を確認する

今後の予定

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

​What are Customer Wallets?

​仕組み

​自動セットアップ

​マルチ通貨対応

​ウォレットの操作

​顧客残高の確認

Get Customer Wallet Balances

​資金の追加または差し引き

Create Customer Wallet Ledger Entry

​取引履歴の表示

List Customer Wallet Ledger Entries

​実際の使用例

​ウォレットへの返金

​ウェルカムボーナス／プロモーション残高

​ウォレットからのサブスクリプション支払い

​前払い請求システム

​マルチカレンシー対応

​ベストプラクティス

​重複取引を防止する

​課金前に残高を確認する

​今後の予定

What are Customer Wallets?

仕組み

自動セットアップ

マルチ通貨対応

ウォレットの操作

顧客残高の確認

資金の追加または差し引き

取引履歴の表示

実際の使用例

ウォレットへの返金

ウェルカムボーナス／プロモーション残高

ウォレットからのサブスクリプション支払い

前払い請求システム

マルチカレンシー対応

ベストプラクティス

重複取引を防止する

課金前に残高を確認する

今後の予定