고객 지갑

Get Customer Wallets

통화별 고객 금전 잔액을 확인합니다.

Create Ledger Entry

고객 지갑에 자금을 추가하거나 차감합니다.

List Ledger Entries

페이지네이션을 사용해 전체 거래 내역을 확인합니다.

고객 지갑이란?

고객 지갑은 사용자를 위한 실제 자금을 보관하는 금전 잔액 계정입니다. 고객 계정을 생성하면 모든 고객에게 지갑이 자동으로 생성됩니다. 다음과 같은 용도로 지갑을 사용할 수 있습니다:

향후 구독 결제를 위한 선불 자금 보관
카드 환불 대신 지갑 잔액으로 환불 처리
가입 보너스나 로열티 보상과 같은 프로모션 잔액 지급
청구 중 지갑 자금을 청구서에 자동 적용
상세 원장 내역으로 금전 거래 추적

고객 계정을 생성하면 모든 고객에게 지갑이 자동으로 생성됩니다. 지갑은 USD와 INR 통화를 지원하며, 각 통화별로 별도의 금전 잔액을 보관합니다.

고객 지갑 ≠ Credit-Based Billing고객 지갑은 청구서와 구독 결제에 적용할 수 있는 실제 금전 잔액(USD, INR)을 보관합니다.가상 사용 단위(API 호출, 토큰, 컴퓨팅 시간)를 추적하려는 경우에는 대신 Credit-Based Billing을 참조하세요.

작동 방식

고객 지갑에는 고객이 구매에 사용할 수 있는 자금이 보관됩니다. 고객에게 청구서나 반복 구독 요금이 발생하면 먼저 지갑 잔액을 확인합니다. 사용 가능한 자금이 있으면 기본 결제 수단으로 청구하기 전에 해당 자금이 청구서에 자동으로 적용됩니다.

자동 설정

새 고객을 생성하면 Dodo Payments 자동으로 잔액이 0인 지갑을 생성합니다. 지갑은 API를 통해 즉시 자금을 받을 수 있는 상태가 됩니다.

다중 통화 지원

각 지갑은 여러 통화의 잔액을 보관할 수 있습니다:

integer

미국 달러 잔액(센트 단위로 저장)

integer

인도 루피 잔액(파이세 단위로 저장)

현재 USD 및 INR 잔액만 사용할 수 있습니다. 더 많은 통화가 곧 추가될 예정입니다.

지갑 사용

고객 잔액 확인

모든 통화에 걸쳐 고객이 보유한 자금의 양을 확인합니다. 구매를 처리하기 전에 사용 가능한 잔액을 확인하거나 애플리케이션 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}`
});

Indian Customers

인도 고객을 위한 INR 자금을 관리합니다.

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

권장 사항

중복 거래 방지

멱등성 키를 사용하여 동일한 이벤트에 대해 실수로 자금을 두 번 추가하거나 차감하지 않도록 합니다.

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

청구 전 잔액 확인

지갑에서 대규모 거래를 처리하기 전에 고객에게 충분한 자금이 있는지 확인합니다.

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

향후 업데이트

다음 기능이 향후 릴리스에 추가될 예정입니다:

잔액 만료: 일정 기간이 지나면 자금이 만료되도록 설정
향상된 분석: 상세한 지출 보고서 및 잔액 추이
추가 Webhooks: 잔액 변경 및 잔액 부족 알림에 대한 실시간 알림

기본 자금 추가 및 차감 작업부터 시작한 다음, 비즈니스가 성장함에 따라 더욱 복잡한 자동 청구 워크플로를 통합하세요.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

고객 지갑이란?

작동 방식

자동 설정

다중 통화 지원

지갑 사용

고객 잔액 확인

Get Customer Wallet Balances

자금 추가 또는 차감

Create Customer Wallet Ledger Entry

거래 내역 확인

List Customer Wallet Ledger Entries

실제 사용 사례

지갑으로 환불

가입 보너스 / 프로모션 잔액

지갑 잔액으로 구독 결제

선불 청구 시스템

다중 통화 지원

권장 사항

중복 거래 방지

청구 전 잔액 확인

향후 업데이트

Get Customer Wallets

Create Ledger Entry

List Ledger Entries

​고객 지갑이란?

​작동 방식

​자동 설정

​다중 통화 지원

​지갑 사용

​고객 잔액 확인

Get Customer Wallet Balances

​자금 추가 또는 차감

Create Customer Wallet Ledger Entry

​거래 내역 확인

List Customer Wallet Ledger Entries

​실제 사용 사례

​지갑으로 환불

​가입 보너스 / 프로모션 잔액

​지갑 잔액으로 구독 결제

​선불 청구 시스템

​다중 통화 지원

​권장 사항

​중복 거래 방지

​청구 전 잔액 확인

​향후 업데이트

고객 지갑이란?

작동 방식

자동 설정

다중 통화 지원

지갑 사용

고객 잔액 확인

자금 추가 또는 차감

거래 내역 확인

실제 사용 사례

지갑으로 환불

가입 보너스 / 프로모션 잔액

지갑 잔액으로 구독 결제

선불 청구 시스템

다중 통화 지원

권장 사항

중복 거래 방지

청구 전 잔액 확인

향후 업데이트