> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Dompet Pelanggan

> Kelola saldo moneter prabayar untuk pelanggan Anda. Danai dompet, terapkan saldo ke faktur langganan, tangani refund sebagai dana dompet, dan lacak riwayat transaksi.

<CardGroup cols={3}>
  <Card title="Get Customer Wallets" icon="code" href="/api-reference/customers/get-customer-wallets">
    Periksa saldo moneter pelanggan dalam berbagai mata uang.
  </Card>

  <Card title="Create Ledger Entry" icon="plus" href="/api-reference/customers/post-customer-wallets-ledger-entries">
    Tambahkan atau kurangi dana dari dompet pelanggan.
  </Card>

  <Card title="List Ledger Entries" icon="list" href="/api-reference/customers/get-customer-wallets-ledger-entries">
    Lihat riwayat transaksi lengkap dengan pagination.
  </Card>
</CardGroup>

## Apa itu Dompet Pelanggan?

Dompet pelanggan adalah akun saldo moneter yang menyimpan dana nyata untuk pengguna Anda. Setiap pelanggan otomatis mendapatkan satu dompet saat Anda membuat akun mereka. Anda dapat menggunakan dompet ini untuk:

* **Menyimpan dana prabayar** untuk pembayaran langganan di masa mendatang
* **Menangani refund** sebagai saldo dompet, bukan refund kartu
* **Memberikan saldo promosi** seperti bonus selamat datang atau reward loyalitas
* **Menerapkan dana dompet ke faktur** secara otomatis selama penagihan
* **Melacak transaksi moneter** dengan riwayat ledger yang terperinci

<Info>
  Setiap pelanggan otomatis mendapatkan dompet saat Anda membuat akun mereka. Dompet mendukung mata uang USD dan INR dengan saldo moneter terpisah untuk masing-masing mata uang.
</Info>

<Warning>
  **Dompet Pelanggan ≠ Penagihan Berbasis Kredit**

  Dompet Pelanggan menyimpan **saldo moneter nyata** (USD, INR) yang dapat diterapkan ke faktur dan pembayaran langganan.

  Jika Anda ingin melacak unit penggunaan virtual (panggilan API, token, jam komputasi), lihat [Penagihan Berbasis Kredit](/features/credit-based-billing).
</Warning>

<Frame>
  <img src="https://mintcdn.com/dodopayments/9oQrV7vsGpxeyDkL/images/customer/customer-wallet.png?fit=max&auto=format&n=9oQrV7vsGpxeyDkL&q=85&s=a4a7ff3c89f4074f37e19b8d99d49ef5" alt="Customer Wallets" style={{ maxHeight: '500px', width: 'auto' }} width="2860" height="1492" data-path="images/customer/customer-wallet.png" />
</Frame>

## Cara Kerjanya

Dompet pelanggan menyimpan dana yang dapat digunakan pelanggan untuk pembelian mereka. Saat pelanggan memiliki faktur atau tagihan langganan berulang, saldo dompet mereka akan diperiksa terlebih dahulu. Dana yang tersedia akan otomatis diterapkan ke faktur sebelum metode pembayaran utama mereka ditagih.

### Penyiapan Otomatis

Saat Anda membuat pelanggan baru, Dodo Payments secara otomatis membuat dompet dengan saldo nol. Dompet tersebut siap menerima dana segera melalui API kami.

### Dukungan Multi-Mata Uang

Setiap dompet dapat menyimpan saldo dalam mata uang yang berbeda:

<ResponseField name="USD Balance" type="integer">
  Saldo dalam Dolar AS (disimpan dalam sen)
</ResponseField>

<ResponseField name="INR Balance" type="integer">
  Saldo dalam Rupee India (disimpan dalam paise)
</ResponseField>

<Info>
  Saat ini, hanya saldo **USD** dan **INR** yang tersedia. Lebih banyak mata uang akan segera hadir.
</Info>

## Menggunakan Dompet

### Memeriksa Saldo Pelanggan

Lihat jumlah dana yang dimiliki pelanggan dalam semua mata uang. Hal ini berguna untuk memverifikasi saldo yang tersedia sebelum memproses pembelian atau menampilkan saldo di UI aplikasi Anda.

<Card title="Get Customer Wallet Balances" icon="wallet" href="/api-reference/customers/get-customer-wallets">
  Periksa saldo moneter dompet pelanggan dalam semua mata uang yang didukung.
</Card>

### Menambahkan atau Mengurangi Dana

Danai dompet pelanggan (seperti bonus selamat datang atau saldo refund) atau kurangi dana (seperti biaya langganan). Anda dapat memberikan alasan untuk setiap transaksi guna menjaga audit trail yang jelas.

<Note>
  Field `entry_type` menggunakan `'credit'` untuk menambahkan dana ke dompet dan `'debit'` untuk mengurangi dana dari dompet.
</Note>

<Card title="Create Customer Wallet Ledger Entry" icon="plus" href="/api-reference/customers/post-customer-wallets-ledger-entries">
  Tambahkan atau kurangi dana dari dompet pelanggan.
</Card>

### Melihat Riwayat Transaksi

Lihat setiap transaksi kredit dan debit pelanggan. Ledger terperinci ini membantu Anda merekonsiliasi akun dan memberikan transparansi kepada pelanggan.

<Card title="List Customer Wallet Ledger Entries" icon="list" href="/api-reference/customers/get-customer-wallets-ledger-entries">
  Lihat setiap transaksi moneter pelanggan.
</Card>

## Contoh di Dunia Nyata

### Refund ke Dompet

Saat pelanggan meminta refund, Anda dapat menambahkan jumlah tersebut ke saldo dompet mereka alih-alih melakukan refund kartu tradisional. Dengan demikian, dana tetap berada dalam ekosistem Anda untuk pembelian di masa mendatang.

```javascript theme={null}
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 Selamat Datang / Saldo Promosi

Berikan bonus moneter selamat datang kepada pelanggan baru untuk mendorong pembelian pertama mereka.

```javascript theme={null}
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}`
  });
}
```

### Pembayaran Langganan dari Dompet

Kurangi dana dari dompet untuk menutupi biaya langganan atau pembelian manual.

```javascript theme={null}
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');
    }
  }
}
```

### Sistem Penagihan Prabayar

Izinkan pelanggan mendanai akun mereka di awal dan menggunakan saldo tersebut secara bertahap.

<Steps>
  <Step title="Add Initial Funds">
    Tambahkan dana ke dompet pelanggan saat mereka melakukan deposit.

    ```javascript theme={null}
    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}`
    });
    ```
  </Step>

  <Step title="Apply Balance to Purchases">
    Kurangi saldo saat pelanggan menggunakan layanan Anda atau memperbarui langganan.

    ```javascript theme={null}
    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}`
    });
    ```
  </Step>

  <Step title="Monitor Balances">
    Periksa apakah dana pelanggan mulai menipis untuk meminta mereka melakukan top-up.

    ```javascript theme={null}
    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);
    }
    ```
  </Step>
</Steps>

### Dukungan Multi-Mata Uang

Kelola saldo moneter terpisah untuk pelanggan di berbagai wilayah.

<AccordionGroup>
  <Accordion title="US Customers">
    Kelola dana USD untuk pelanggan yang berbasis di AS.

    ```javascript theme={null}
    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}`
    });
    ```
  </Accordion>

  <Accordion title="Indian Customers">
    Kelola dana INR untuk pelanggan di India.

    ```javascript theme={null}
    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}`
    });
    ```
  </Accordion>
</AccordionGroup>

## Praktik Terbaik

### Mencegah Transaksi Duplikat

Gunakan idempotency keys untuk memastikan Anda tidak sengaja menambahkan atau mengurangi dana dua kali untuk event yang sama.

```javascript theme={null}
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;
  }
}
```

### Memeriksa Saldo Sebelum Menagih

Pastikan pelanggan memiliki dana yang cukup sebelum mencoba memproses transaksi besar dari dompet.

```javascript theme={null}
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;
}
```

## Apa yang Akan Hadir Selanjutnya

<Warning>
  Fitur-fitur berikut direncanakan untuk rilis mendatang:
</Warning>

* **Kedaluwarsa Saldo**: Atur dana agar kedaluwarsa setelah jangka waktu tertentu
* **Analytics yang Lebih Baik**: Laporan pengeluaran dan tren saldo yang terperinci
* **Lebih Banyak Webhook**: Notifikasi real-time untuk perubahan saldo dan peringatan saldo rendah

<Tip>
  Mulailah dengan operasi pendanaan dan pengurangan dana dasar, lalu integrasikan workflow penagihan otomatis yang lebih kompleks seiring pertumbuhan bisnis Anda.
</Tip>