OOLIN 서비스 구조

OOLIN Wallet API는 고객 계정의 자금 수취·보관·이동과 거래 기록 조회를 제공합니다. 고객사 백엔드는 이를 사용해 고객 지갑이나 가맹점 결제 서비스를 구현합니다. 고객의 로그인, 주문, 가맹점 정보는 고객사 서비스에서 관리하고 Wallet API의 계정·거래와 연결합니다.

고객 애플리케이션과 Wallet API의 관계

고객 앱 또는 가맹점 서비스
  → 고객사 백엔드: 로그인·작업 권한·주문 관리·요청 서명
  → OOLIN Wallet API: 계정·입금·이체·출금·잔액·원장
  → 고객사 백엔드: 거래 결과 조회·업무 상태 갱신
  → 고객 화면: 잔액·결제 결과·정산 진행 상황

고객 앱은 인증된 고객사 백엔드를 호출합니다. 백엔드는 고객과 작업 권한을 확인한 뒤 API Key와 HMAC Key를 사용해 Wallet API 요청에 서명합니다. 자격 증명은 서버 측에서 관리하며 브라우저나 모바일 앱에 전달하지 않습니다.

HMAC 인증은 Wallet API 요청의 인증과 무결성을 확인합니다. 고객이 특정 계정에서 출금할 권한이 있는지는 고객사 백엔드가 별도로 판단해야 합니다. API 인증과 고객 작업 인가는 서로 다른 책임입니다.

역할과 책임

항목	고객사 백엔드	OOLIN Wallet API
고객·가맹점 식별	로그인·업무 식별자를 관리하고 uid와 연결	uid에 연결된 계정 제공
계정 준비	기존 계정을 선택하거나 생성을 요청하고 연결 정보 저장	계정 생성·조회와 계정 상태 제공
입금	입금 목적지를 표시하고 입금 완료 후 업무 반영	입금 주소 할당, 입금 처리 상태·잔액 제공
결제·출금	권한·주문·지급 의도 확인, 요청 제출	자금 이동 처리와 거래 상세 제공
결과 복구	업무 ID와 요청 ID를 저장하고 결과 재조회	거래 ID 또는 client_request_id로 결과 조회
거래 대사	주문·정산과 거래·원장을 비교	잔액, 원장과 대사 조회 제공

기능과 리소스 연결

구현할 기능	사용하는 API 리소스
고객 지갑 준비	POST /accounts, GET /users/{uid}/accounts
자산과 네트워크 선택	/asset-types, /networks, /assets
입금 목적지 발급	/accounts/{account_id}/deposit-addresses
입금 내역과 완료 확인	/deposits, /deposits/{deposit_id}
사용 가능 자금 표시	/accounts/{account_id}/balances
계정 간 결제	POST /withdrawals/internal
외부 주소로 정산	POST /withdrawals/quote, POST /withdrawals
거래 결과와 금액 변동 확인	/withdrawals/{withdrawal_id}, /accounts/{account_id}/ledger

지갑 기능과 결제 활용

고객 지갑은 계정 준비, 입금 주소 발급, 입금 확인, 잔액·원장 조회와 외부 출금으로 구성합니다. 고객은 자금을 입금해 보관하고, 사용 가능 잔액을 확인하며, 원하는 외부 주소로 출금합니다.

다른 OOLIN 계정으로 자금을 보내려면 내부이체를 사용합니다. Digital Payment는 이를 고객 USER 계정에서 가맹점 BUSINESS 계정으로 보내는 결제로 활용하고, 가맹점의 외부 출금을 정산 업무에 연결한 사례입니다. 같은 Wallet API 리소스를 조합하며 별도 /payments API를 호출하지 않습니다.

시나리오	주요 흐름	고객사에서 연결할 업무
고객 지갑	계정 → 외부 입금 → 잔액·거래 내역 → 외부 출금	고객과 계정, 입금 내역, 출금 신청
계정 간 자금 이동	송신 계정 → 내부이체 → 수신 계정	송신·수신 계정과 이체 목적
Digital Payment	고객 충전 → 가맹점 결제 → 가맹점 정산	주문과 결제 거래, 가맹점과 정산 거래

요청 접수와 업무 완료

외부 입금은 컨펌과 처리 시간이 필요하고 외부 출금은 요청 접수 후 온체인 전송을 진행합니다. 생성 응답의 거래 ID는 이후 결과를 조회할 식별자입니다. 고객에게 성공을 표시할 시점은 거래별 완료 조건으로 결정합니다.

예를 들어 고객이 외부 출금을 신청하면 고객사 서비스는 출금 신청과 withdrawal_id를 연결하고 대기 상태를 유지합니다. 출금 상세의 status와 user_status가 COMPLETED이며 tx_hash가 유효할 때 출금을 완료 처리합니다. 가맹점 정산도 같은 출금 완료 조건을 사용합니다.

생성 응답을 받지 못하면 저장한 client_request_id로 기존 거래를 조회합니다. 고객사 주문 ID, client_request_id, Wallet 거래 ID를 연결하면 재시작 후에도 같은 업무를 추적할 수 있습니다. 복구 절차는 멱등성과 중복 요청 방지를 참고합니다.

연동 범위 선택

고객의 입금·잔액·외부 출금이 필요하면 Wallet 튜토리얼을 진행합니다. 고객과 가맹점 사이의 결제·정산이 필요하면 Digital Payment 튜토리얼을 진행합니다. 두 흐름의 계정 관계는 사용자·계정·지갑 모델에서 이어서 설명합니다.