Customer Wallets

Get Customer Wallets

Lấy số dư của khách hàng theo từng loại tiền tệ.

Create Ledger Entry

Cộng tiền vào hoặc trừ tiền khỏi ví.

List Ledger Entries

Phân trang qua mọi giao dịch trong ví.

Ví khách hàng là gì?

Ví khách hàng lưu giữ tiền thật cho khách hàng, với một số dư riêng cho mỗi loại tiền tệ. Sử dụng ví để:

Lưu trữ tiền trả trước cho các khoản thanh toán đăng ký trong tương lai
Xử lý hoàn tiền dưới dạng số dư trong ví thay vì hoàn tiền về thẻ
Cấp số dư khuyến mãi, chẳng hạn như tiền thưởng chào mừng hoặc phần thưởng khách hàng thân thiết
Tự động áp dụng tiền trong ví vào các khoản phí đăng ký tại thời điểm lập hóa đơn
Theo dõi mọi giao dịch trong sổ cái, cùng số dư trước và sau giao dịch

Bạn không cần tự tạo ví. Ví của khách hàng cho một loại tiền tệ sẽ được tạo với số dư bằng không vào lần đầu tiên bạn thêm một mục sổ cái bằng loại tiền tệ đó. Cho đến lúc đó, Get Customer Wallets sẽ không trả về mục nào cho loại tiền tệ đó.

Customer Wallets ≠ Credit-Based BillingVí khách hàng lưu giữ tiền thật mà Dodo Payments áp dụng vào các khoản phí đăng ký.Để theo dõi các đơn vị sử dụng ảo như lệnh gọi API, token hoặc giờ tính toán, hãy sử dụng Credit-Based Billing thay thế.

How It Works

Khi một gói đăng ký gia hạn hoặc việc thay đổi gói tạo ra một khoản phí, Dodo Payments trước tiên áp dụng số dư trong ví của khách hàng bằng loại tiền tệ đó, sau đó tính phí vào phương thức thanh toán cho phần còn lại. Nếu số dư chỉ đủ thanh toán một phần khoản phí, ví sẽ thanh toán phần đó.

Automatic Setup

Bạn không cần thiết lập gì cả. Thêm một mục sổ cái thông qua API hoặc nhấp vào Apply Credit/Debit trên tab Wallets của khách hàng trong dashboard, và ví cho loại tiền tệ đó sẽ sẵn sàng sử dụng.

Multi-Currency Support

Mỗi loại tiền tệ có một số dư riêng. Mỗi ví trong phản hồi Get Customer Wallets có currency và balance theo đơn vị nhỏ nhất của loại tiền tệ, đồng thời phản hồi thêm total_balance_usd, là tổng của tất cả số dư được quy đổi sang USD. Các mục sổ cái chấp nhận những loại tiền tệ sau:

integer

Balance in US Dollars (stored in cents)

integer

Balance in Euros (stored in cents)

integer

Balance in Pounds Sterling (stored in pence)

Ví khách hàng lưu giữ số dư bằng USD, EUR và GBP. Ví INR native đã ngừng hỗ trợ được mô tả trong Payout Structure là ví chi trả cho merchant của bạn, không phải ví khách hàng. INR vẫn được hỗ trợ làm loại tiền tệ giao dịch cho các gói đăng ký qua UPI, RuPay và thẻ Ấn Độ.

Working with Wallets

Check Customer Balances

Lấy số dư của khách hàng bằng mọi loại tiền tệ, chẳng hạn để xác nhận số dư trước khi mua hàng hoặc hiển thị số dư trong ứng dụng của bạn.

Get Customer Wallet Balances

Lấy số dư ví của khách hàng bằng tất cả các loại tiền tệ.

Add or Deduct Funds

Cộng tiền, chẳng hạn tiền thưởng chào mừng hoặc số dư hoàn tiền, hoặc trừ tiền, chẳng hạn một khoản phí thủ công. entry_type, currency và amount là bắt buộc. amount là một số nguyên dương theo đơn vị nhỏ nhất của loại tiền tệ. Thêm một reason (tối đa 500 ký tự) cho audit trail của bạn và một idempotency_key để ngăn các mục trùng lặp. Phản hồi là ví đã được cập nhật.

entry_type là 'credit' để cộng tiền vào ví và 'debit' để trừ tiền khỏi ví. Giao dịch ghi nợ lớn hơn số dư sẽ thất bại với 400.

Create Customer Wallet Ledger Entry

Cộng tiền vào hoặc trừ tiền khỏi ví của khách hàng.

View Transaction History

Liệt kê mọi giao dịch ghi có và ghi nợ của một khách hàng, có phân trang và bộ lọc currency tùy chọn. Mỗi mục có một event_type (payment, payment_reversal, refund, refund_reversal, dispute, dispute_reversal hoặc merchant_adjustment), amount, cùng before_balance và after_balance. Sử dụng sổ cái để đối soát tài khoản và trả lời câu hỏi của khách hàng.

List Customer Wallet Ledger Entries

Liệt kê mọi giao dịch trong ví của một khách hàng.

Real-World Examples

Các ví dụ sử dụng SDK TypeScript. client là một client DodoPayments, được tạo như trong Integration Guide.

Hoàn tiền vào ví

Để hoàn tiền cho khách hàng dưới dạng số dư trong ví thay vì hoàn về thẻ, hãy thêm số tiền bằng một mục ghi có. Khoản tiền này sẽ ở lại với doanh nghiệp của bạn để khách hàng sử dụng cho lần mua tiếp theo.

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

Một khoản ghi có trong sổ cái không hoàn lại khoản thanh toán ban đầu. Khi bạn hoàn tiền một khoản thanh toán thông qua Refunds API, Dodo Payments sẽ tự động trả lại phần mà ví đã thanh toán vào ví.

Tiền thưởng chào mừng / Số dư khuyến mãi

Tặng khách hàng mới một khoản tiền thưởng chào mừng để khuyến khích họ mua hàng lần đầu.

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

Thanh toán gói đăng ký từ ví

Trừ tiền từ ví để thanh toán một khoản phí mà bạn tự lập hóa đơn. Việc gia hạn không cần bước này vì Dodo Payments tự động áp dụng số dư cho các khoản gia hạn.

async function deductForPurchase(customerId, purchaseAmount, purchaseId) {
  try {
    await client.customers.wallets.ledgerEntries.create(customerId, {
      amount: purchaseAmount,
      currency: 'USD',
      entry_type: 'debit',
      reason: `Manual charge for purchase ${purchaseId}`,
      idempotency_key: `charge_${purchaseId}`
    });
  } catch (error) {
    if (error.status === 400) {
      console.log('Insufficient wallet balance');
    }
  }
}

Hệ thống thanh toán trả trước

Cho phép khách hàng nạp tiền vào tài khoản trước và sử dụng dần số dư đó theo thời gian. customerId, paymentId và purchaseId là các mã định danh do bạn tự đặt cho khách hàng, khoản nạp và giao dịch mua.

Add Initial Funds

Cộng tiền vào ví của khách hàng khi họ thực hiện nạp tiền.

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

Trừ tiền khỏi số dư khi khách hàng sử dụng dịch vụ của bạn.

await client.customers.wallets.ledgerEntries.create(customerId, {
  amount: 1500, // $15.00 charge
  currency: 'USD',
  entry_type: 'debit',
  reason: 'Service purchase - usage charge',
  idempotency_key: `purchase_${purchaseId}`
});

Monitor Balances

Kiểm tra xem khách hàng có sắp hết tiền hay không và nhắc họ nạp thêm.

const wallets = await client.customers.wallets.list(customerId);
const usdWallet = wallets.items.find(w => w.currency === 'USD');
const balance = usdWallet?.balance ?? 0; // no USD wallet yet means a zero balance

if (balance < 1000) { // Less than $10.00
  // sendLowBalanceNotification is your own function, for example an email
  await sendLowBalanceNotification(customerId, balance);
}

Hỗ trợ đa tiền tệ

Duy trì các số dư riêng cho khách hàng ở những khu vực khác nhau.

US Customers

Quản lý tiền USD cho khách hàng ở Hoa Kỳ.

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

Quản lý tiền EUR cho khách hàng ở châu Âu.

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

Quản lý tiền GBP cho khách hàng ở Vương quốc Anh.

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

Thực tiễn tốt nhất

Ngăn giao dịch trùng lặp

Truyền một idempotency_key được tạo từ sự kiện gây ra mục đó, chẳng hạn ID đơn hàng hoặc khoản thanh toán, để việc thử lại không cộng hoặc trừ tiền hai lần. Nếu bạn lặp lại yêu cầu với cùng một key, Dodo Payments sẽ không tạo mục mới và trả về ví hiện tại.

async function addFundsSafely(customerId, amount, reason, eventId) {
  // Derive the key from the event, not from the time, so retries reuse it.
  const idempotencyKey = `credit_${customerId}_${eventId}`;

  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 creates no duplicate entry and
    // returns the wallet, 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;
  }
}

Kiểm tra số dư trước khi tính phí

Trước khi trừ một khoản tiền lớn khỏi ví, hãy xác nhận số dư đủ để thanh toán khoản đó.

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

Điều gì sẽ đến tiếp theo

Ví khách hàng chưa hỗ trợ các tính năng sau:

Hết hạn số dư: Tiền trong ví không hết hạn.
Phân tích: Không có báo cáo chi tiêu hoặc xu hướng số dư. Hãy sử dụng sổ cái để tự xây dựng các báo cáo của bạn.
Webhooks: Không có webhook nào được kích hoạt khi số dư thay đổi và cũng không có cảnh báo số dư thấp. Để theo dõi các thay đổi, hãy liệt kê các mục trong sổ cái.

Bắt đầu với việc nạp và trừ tiền cơ bản, sau đó tự động hóa thêm quy trình thanh toán khi doanh nghiệp của bạn phát triển.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

Ví khách hàng là gì?

How It Works

Automatic Setup

Multi-Currency Support

Working with Wallets

Check Customer Balances

Get Customer Wallet Balances

Add or Deduct Funds

Create Customer Wallet Ledger Entry

View Transaction History

List Customer Wallet Ledger Entries

Real-World Examples

Hoàn tiền vào ví

Tiền thưởng chào mừng / Số dư khuyến mãi

Thanh toán gói đăng ký từ ví

Hệ thống thanh toán trả trước

Hỗ trợ đa tiền tệ

Thực tiễn tốt nhất

Ngăn giao dịch trùng lặp

Kiểm tra số dư trước khi tính phí

Điều gì sẽ đến tiếp theo

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

​Ví khách hàng là gì?

​How It Works

​Automatic Setup

​Multi-Currency Support

​Working with Wallets

​Check Customer Balances

Get Customer Wallet Balances

​Add or Deduct Funds

Create Customer Wallet Ledger Entry

​View Transaction History

List Customer Wallet Ledger Entries

​Real-World Examples

​Hoàn tiền vào ví

​Tiền thưởng chào mừng / Số dư khuyến mãi

​Thanh toán gói đăng ký từ ví

​Hệ thống thanh toán trả trước

​Hỗ trợ đa tiền tệ

​Thực tiễn tốt nhất

​Ngăn giao dịch trùng lặp

​Kiểm tra số dư trước khi tính phí

​Điều gì sẽ đến tiếp theo

Ví khách hàng là gì?

How It Works

Automatic Setup

Multi-Currency Support

Working with Wallets

Check Customer Balances

Add or Deduct Funds

View Transaction History

Real-World Examples

Hoàn tiền vào ví

Tiền thưởng chào mừng / Số dư khuyến mãi

Thanh toán gói đăng ký từ ví

Hệ thống thanh toán trả trước

Hỗ trợ đa tiền tệ

Thực tiễn tốt nhất

Ngăn giao dịch trùng lặp

Kiểm tra số dư trước khi tính phí

Điều gì sẽ đến tiếp theo