핵심 개념

OOLIN 지갑을 연동할 때는 누구의 자금인지, 어떤 자산인지, 지금 사용할 수 있는지, 입출금이 완료됐는지를 각각 구분해야 합니다. 계정, 자산, 잔액, 거래 상세와 원장은 이 질문에 답하는 서로 다른 리소스입니다.

지갑의 기본 흐름

고객 지갑은 계정을 준비하고, 자산을 입금받고, 잔액과 거래 내역을 조회하며, 필요할 때 외부 주소로 출금하는 흐름으로 구성합니다.

고객과 USER 계정 연결
  → 자산·네트워크 선택 및 입금 주소 발급
  → 외부 입금 확인과 잔액 적립
  → 사용 가능 잔액과 거래 내역 조회
  → 외부 출금 요청과 결과 확인

예를 들어 고객이 100 USDT를 입금하고 외부 주소로 20 USDT를 출금한다면, 수수료가 1 USDT인 경우 출금 완료 후 잔액은 79 USDT입니다. 요청 접수 후 완료까지는 21 USDT가 예약되어 사용 가능 잔액과 총 잔액이 달라집니다. 금액과 수수료는 설명용이며 실제 연동에서는 대상 환경의 응답을 사용합니다.

알고 싶은 내용	확인할 리소스	주요 식별자·필드
누구의 지갑인가?	계정	uid, account_id, account_type
어떤 자산을 어느 네트워크로 주고받는가?	자산 유형, 네트워크, 자산	asset_type_id, network_id, asset_id
외부 자산을 어디로 보내야 하는가?	입금 주소	address_id, address, network_id, tag_or_memo
얼마를 지금 사용할 수 있는가?	잔액	available_amount_raw, pending_withdraw_amount_raw
입금·출금·이체가 끝났는가?	입금·출금 상세	deposit_id, withdrawal_id, status, user_status
어떤 거래가 잔액을 바꿨는가?	원장	ledger_id, ref_type, ref_id, entry_type

지갑을 활용한 계정 간 이체와 결제

지갑의 자금을 다른 OOLIN 계정으로 이동할 때는 내부이체를 사용합니다. 외부 주소와 네트워크를 지정하는 출금과 달리, 내부이체는 송신 계정·수신 계정·자산 유형을 지정합니다.

Digital Payment는 이 기능을 고객과 가맹점의 결제로 활용한 사례입니다. 고객 USER 계정에서 가맹점 BUSINESS 계정으로 자금을 보내고, 가맹점은 수취한 자금을 외부 주소로 정산할 수 있습니다. 지갑의 기본 입출금과 동일한 계정·잔액·거래·원장 개념을 사용합니다.

권장 읽기 순서

문서	이해할 내용
OOLIN 서비스 구조	고객 앱·고객사 백엔드·Wallet API의 역할과 지갑·결제 연동 범위
사용자·계정·지갑 모델	사용자와 계정의 관계, USER·BUSINESS 역할, 입금 주소
네트워크와 자산	자산 유형과 네트워크별 자산, ID와 금액 단위
지원 네트워크	메인넷·테스트넷 카탈로그, 이용 가능 범위와 네트워크 확장
입금 주소	계정별 입금 목적지, 자산·네트워크·memo, 발급과 재조회
잔액과 원장	사용 가능·예약·총 잔액의 차이와 거래 대사
입금 처리 흐름	입금 주소 발급부터 입금 발견과 완료 판단까지
출금 처리 흐름	외부 출금의 견적·예약·완료·복구와 내부이체의 차이
거래 상태 모델	상태별 업무 처리와 신규 거래 발견·상태 추적의 차이

개념을 구현으로 연결하기

고객 지갑의 입금·조회·출금은 Wallet 튜토리얼에서 구현합니다. 계정 간 이체를 이용한 고객·가맹점 결제와 정산은 Digital Payment 튜토리얼에서 구현합니다. 요청·응답의 전체 필드는 API Reference에서 확인합니다.

각 금액의 자산·단위, 각 계정의 소유자·환경, 각 주소의 네트워크·memo, 각 거래의 완료 조건을 함께 관리하면 지갑 기능과 활용 시나리오를 일관되게 연결할 수 있습니다.