Get Customer Wallets
각 통화의 고객 잔액을 조회합니다.
Create Ledger Entry
지갑에 자금을 추가하거나 지갑에서 자금을 차감합니다.
List Ledger Entries
모든 지갑 거래를 페이지 단위로 조회합니다.
고객 지갑이란?
고객 지갑은 고객의 실제 금액을 보관하며, 통화별로 하나의 잔액을 가집니다. 지갑을 사용하면 다음을 수행할 수 있습니다:- 선불 자금 보관: 향후 구독 결제에 사용
- 환불 처리: 카드로 환불하는 대신 지갑 잔액으로 처리
- 프로모션 잔액 지급: 가입 보너스 또는 로열티 보상 등
- 지갑 자금을 구독 요금에 자동 적용: 청구 시점에 적용
- 모든 거래 추적: 거래 전후 잔액이 포함된 원장에서 추적
직접 지갑을 생성할 필요는 없습니다. 특정 통화로 원장 항목을 처음 추가하면 해당 통화의 고객 지갑이 잔액 0으로 생성됩니다. 그때까지는 Get Customer Wallets가 해당 통화에 대한 항목을 반환하지 않습니다.

작동 방식
구독이 갱신되거나 요금제 변경으로 요금이 발생하면 Dodo Payments는 먼저 해당 통화의 고객 지갑 잔액을 적용한 다음, 나머지 금액을 결제 수단으로 청구합니다. 잔액이 요금의 일부만 충당하는 경우 지갑에서 해당 부분을 지불합니다.자동 설정
별도로 설정할 필요가 없습니다. API를 통해 원장 항목을 추가하거나 대시보드의 고객 Wallets 탭에서 Apply Credit/Debit을 클릭하면 해당 통화의 지갑을 바로 사용할 수 있습니다.다중 통화 지원
통화마다 고유한 잔액이 있습니다. Get Customer Wallets 응답의 각 지갑에는 가장 작은 통화 단위로 표시된currency 및 balance가 있으며, 응답에는 모든 잔액을 USD로 환산한 합계인 total_balance_usd도 포함됩니다. 원장 항목은 다음 통화를 지원합니다:
integer
미국 달러 잔액(센트 단위로 저장)
integer
유로 잔액(센트 단위로 저장됨)
integer
파운드 스털링 잔액(펜스 단위로 저장됨)
고객 지갑은 USD, EUR 및 GBP 잔액을 보관합니다. Payout Structure에 설명된 중단된 INR native wallet은 고객 지갑이 아니라 merchant payout wallet입니다. INR은 UPI, RuPay 및 인도 카드 구독의 거래 통화로 계속 지원됩니다.
Wallet 사용
고객 잔액 확인
예를 들어 구매 전에 잔액을 확인하거나 앱에 표시하기 위해 모든 통화의 고객 잔액을 조회합니다.Get Customer Wallet Balances
모든 통화의 고객 지갑 잔액을 조회합니다.
자금 추가 또는 차감
가입 보너스나 환불 잔액과 같은 자금을 추가하거나, 수동 청구와 같이 자금을 차감합니다.entry_type, currency 및 amount가 필요합니다. amount는 가장 작은 통화 단위로 표시되는 양의 정수입니다. 감사 추적을 위해 reason(최대 500자)를 추가하고, 중복을 방지하려면 idempotency_key를 추가하세요. 응답은 업데이트된 지갑입니다.
지갑에 자금을 추가하려면
entry_type는 'credit'이고, 자금을 차감하려면 'debit'입니다. 잔액보다 큰 금액을 debit하면 400와 함께 실패합니다.Create Customer Wallet Ledger Entry
고객 지갑에 자금을 추가하거나 고객 지갑에서 자금을 차감합니다.
거래 내역 보기
페이지네이션 및 선택적currency 필터를 사용하여 고객의 모든 credit 및 debit을 조회합니다. 각 항목에는 event_type(payment, payment_reversal, refund, refund_reversal, dispute, dispute_reversal 또는 merchant_adjustment), amount, 그리고 before_balance 및 after_balance가 포함됩니다. 원장을 사용하여 계정을 조정하고 고객 문의에 답변하세요.
List Customer Wallet Ledger Entries
고객의 모든 지갑 거래를 조회합니다.
실제 사용 사례
예제에서는 TypeScript SDK를 사용합니다.client는 Integration Guide에 설명된 방식으로 생성한 DodoPayments client입니다.
지갑으로 환불
고객의 카드로 환불하는 대신 지갑 잔액으로 환불하려면 credit 항목으로 금액을 추가하세요. 자금은 고객의 다음 구매를 위해 비즈니스에 남아 있습니다.원장 credit은 원래 결제를 환불하지 않습니다. Refunds API를 통해 결제를 환불하면 Dodo Payments는 지갑에서 지불된 금액 중 해당 부분을 자동으로 지갑에 반환합니다.
가입 보너스 / 프로모션 잔액
신규 고객에게 가입 보너스를 제공하여 첫 구매를 유도하세요.지갑에서 구독 결제
직접 청구하는 요금을 결제하기 위해 지갑에서 자금을 차감합니다. 갱신에는 이 단계가 필요하지 않습니다. Dodo Payments가 잔액을 자동으로 적용하기 때문입니다.선불 청구 시스템
고객이 계정에 미리 자금을 충전하고 시간이 지남에 따라 해당 잔액을 사용하도록 하세요.customerId, paymentId 및 purchaseId는 고객, 입금 및 구매를 식별하기 위해 직접 사용하는 식별자입니다.
1
Add Initial Funds
고객이 입금하면 고객의 지갑에 자금을 추가합니다.
2
Apply Balance to Purchases
고객이 서비스를 사용할 때 잔액에서 차감합니다.
3
Monitor Balances
고객의 잔액이 부족해지고 있는지 확인하고 충전을 안내합니다.
다중 통화 지원
서로 다른 지역의 고객을 위해 잔액을 별도로 관리하세요.US Customers
US Customers
미국 기반 고객의 USD 자금을 관리합니다.
European Customers
European Customers
유럽 기반 고객의 EUR 자금을 관리합니다.
UK Customers
UK Customers
영국 기반 고객의 GBP 자금을 관리합니다.
모범 사례
중복 거래 방지
주문 또는 결제 ID와 같이 항목을 생성한 이벤트에서 파생한idempotency_key를 전달하여 재시도 시 자금이 두 번 추가되거나 차감되지 않도록 하세요. 동일한 key로 요청을 반복하면 Dodo Payments는 새 항목을 생성하지 않고 현재 지갑을 반환합니다.
청구 전 잔액 확인
지갑에서 큰 금액을 차감하기 전에 잔액이 해당 금액을 충당할 수 있는지 확인하세요.다음 단계
Customer wallets는 다음 기능을 지원하지 않습니다:- 잔액 만료: 지갑 자금은 만료되지 않습니다.
- 분석: 지출 보고서나 잔액 추세가 제공되지 않습니다. 원장을 사용하여 직접 구축하세요.
- Webhooks: 잔액 변경 시 webhook이 실행되지 않으며 잔액 부족 알림도 없습니다. 변경 사항을 추적하려면 원장 항목을 조회하세요.