입금 처리 흐름

입금은 고객이 외부에서 보낸 자산을 OOLIN 계정의 잔액으로 받는 과정입니다. 입금 주소를 발급한 시점, 전송이 발견된 시점, 잔액 적립이 완료된 시점은 서로 다릅니다. 고객 지갑은 입금 상세의 status로 완료 여부를 판단합니다.

전송 전에 준비할 목적지의 구성과 발급·재조회는 입금 주소에서 설명합니다. 이 문서는 그 목적지로 실제 자산이 전송된 이후의 처리를 다룹니다.

외부 입금의 기본 단계

고객 계정과 자산·네트워크 선택
  → 입금 주소와 필요한 memo 안내
  → 고객의 외부 전송
  → 입금 레코드 발견
  → 컨펌·처리 상태 추적
  → COMPLETED 확인과 잔액·원장 조회

단계	확인할 내용	고객 지갑에서의 의미
목적지 준비	계정, 지원 자산·네트워크, 주소·memo	고객에게 입금 방법 제공
외부 전송	선택한 자산과 네트워크로 전송	전송만으로 지갑 적립 완료는 아님
입금 발견	deposit_id, type, 금액, status	입금 내역 표시와 상태 추적 시작
처리 진행	컨펌·승인·검증 등 상세 상태	아직 완료되지 않은 입금
입금 완료	status: COMPLETED, confirmed_at	고객 입금 완료 처리
기록 확인	잔액과 DEPOSIT / CREDIT 원장	적립된 금액 확인과 거래 대사

컨펌은 블록체인에서 전송이 확정되는 정도를 확인하는 과정입니다. 필요한 처리 시간은 네트워크와 입금 정책에 따라 달라지므로 고정 시간 경과만으로 입금을 완료 처리하지 않습니다.

고객 지갑의 100 USDT 입금 예시

고객의 USDT 잔액이 0인 상태에서 올바른 입금 목적지로 100 USDT를 전송했다고 가정합니다.

• 입금이 발견되면 입금 내역에 100 USDT와 처리 상태를 표시합니다.
• 비최종 상태에서는 해당 deposit_id를 조회하며 고객 충전 완료를 기다립니다.
• COMPLETED가 되면 USDT 잔액과 연결된 입금 원장을 확인합니다.
• 다른 동시 거래가 없다면 완료된 입금은 잔액을 100 USDT 증가시킵니다.

Explorer에서 전송을 확인하거나 tx_hash가 있다는 사실만으로 계정 적립 완료를 판단하지 않습니다. 고객사에서 입금 상태에 따라 주문·포인트 등을 반영한다면 같은 완료 응답을 반복 처리해도 업무 효과가 중복되지 않도록 구현합니다.

신규 입금 발견과 상태 추적

입금 목록은 새 레코드를 찾고, 상세 조회는 이미 발견한 입금의 이후 상태를 확인합니다.

목적	API	저장할 값
신규 외부 입금 발견	GET /deposits?account_id={account_id}&type=EXTERNAL&after_id={cursor}	deposit_id, 목록의 next_cursor
기존 입금 상태 확인	GET /deposits/{deposit_id}?type=EXTERNAL	마지막 상태, 다음 확인 대상

ID cursor는 이후 상태 변경을 다시 반환하지 않습니다. 처음 발견한 입금이 처리 중이면 cursor가 앞으로 이동한 뒤에도 별도로 상세 조회를 계속합니다. 입금 항목과 cursor를 저장한 후 재시작 시 같은 지점부터 신규 탐지를 재개합니다.

외부 입금과 내부 입금은 ID 범위가 다를 수 있으므로 (type, deposit_id)를 구분하고 cursor도 따로 관리합니다. tx_hash만으로 모든 입금 레코드를 식별하지 않습니다.

성공·진행·환불 상태 구분

입금 API는 user_status 없이 상세 status를 제공합니다.

상태	고객사 처리
PENDING, INSPECTED, APPROVE_PENDING, APPROVED, VERIFIED	완료로 표시하지 않고 상세 조회 유지
REFUND_REQUIRED, REFUND_REQUESTED, REFUND_PENDING	입금 성공으로 반영하지 않고 환불 진행과 운영 확인
COMPLETED	입금 성공 처리와 잔액·원장 대사
REFUNDED, FAILED	성공이 아닌 종료 결과 기록

환불 완료는 지갑 적립 성공과 다른 결과입니다. 지원이 필요하면 입금 ID와 상태를 사용하고 고객사에서 임의의 잔액 보정을 만들지 않습니다. 전체 상태 계약은 상태 코드를 확인합니다.

계정 간 이체로 받은 자금

다른 OOLIN 계정에서 내부이체를 받으면 외부 블록체인 전송 없이 수신 계정의 잔액이 증가합니다. 일반 계정 간 이체와 고객·가맹점 결제 모두 이 방식으로 자금을 수취할 수 있습니다.

내부 입금은 type=INTERNAL로 조회하며 PENDING 또는 COMPLETED로 표시됩니다. 원장에는 INTERNAL_IN / CREDIT이 기록되고 원본 내부이체의 출금 참조와 연결됩니다. 개별 이체·결제의 성공 확인은 원본 출금 상세를 기준으로 합니다.

저장과 재시작 복구

입금 유형·ID, 계정·자산·네트워크, raw 금액·decimals, status, tx_hash, confirmed_at, 마지막 확인 시각을 저장합니다. 목록 cursor와 비최종 입금 목록을 따로 유지하면 신규 입금 발견과 진행 중 입금 추적을 함께 복구할 수 있습니다.

실제 주소 발급과 조회 예제는 입금 주소 발급과 입금 내역 확인을 참고합니다. 적립 이후 잔액·원장의 관계는 잔액과 원장에서 설명합니다.