출금 처리 흐름

고객 지갑에서 외부 주소로 자금을 보내는 작업은 외부 출금입니다. 출금 요청을 접수하면 금액과 수수료를 예약하고, 온체인 전송 결과를 반영한 뒤 완료됩니다. 다른 OOLIN 계정으로 보내는 내부이체는 계정 간 잔액 이동으로 처리됩니다.

외부 출금과 내부이체

구분	외부 출금	내부이체
목적지	선택한 네트워크의 외부 주소	다른 OOLIN 계정
생성 API	POST /withdrawals	POST /withdrawals/internal
주요 입력	송신 계정, 자산 유형, 네트워크, 주소, 금액	송신·수신 계정, 자산 유형, 금액
처리 방식	접수 이후 비동기 온체인 전송	계정 간 즉시 이체
수수료	견적의 fee_amount 확인	0
성공 판단	두 완료 상태와 유효한 tx_hash	두 완료 상태와 request_type: INTERNAL

두 방식 모두 withdrawal_id로 거래 상세를 조회합니다. 내부이체에서는 외부 전송 네트워크나 온체인 tx_hash를 완료 조건으로 요구하지 않습니다.

고객 지갑의 외부 출금 단계

고객 출금 신청과 권한 확인
  → 목적지 주소 검증
  → 출금 견적과 고객 확인
  → 업무 요청 ID 저장
  → 출금 생성과 잔액 예약
  → 상세 조회로 결과 추적
  → 완료 또는 실패 결과 반영

1. 목적지와 견적 확인

선택한 자산·네트워크 조합을 확인하고 /assets/{asset_id}/validate-address로 주소 형식을 검증합니다. 이후 POST /withdrawals/quote로 계정 상태, 금액, 한도, 수수료, 잔액과 전송 유형을 확인합니다.

외부 출금이 목적이면 can_withdraw: true, transfer_type: EXTERNAL인지 확인합니다. 다른 OOLIN 계정의 입금 주소는 내부이체로 판별될 수 있으므로 주소 형식만으로 전송 유형을 결정하지 않습니다.

견적 필드	해석
amount	보낼 원금
fee_amount	원금에 별도로 더해지는 수수료
receive_amount	수취인이 받는 금액
min_amount, max_amount	요청 금액 한도
can_withdraw, reason	현재 출금 가능 여부와 불가 사유

계정에 필요한 금액은 amount + fee_amount입니다. 견적은 잔액을 예약하거나 성공을 보장하지 않으므로 실제 생성 응답도 확인합니다.

2. 요청 저장과 생성

고객사 출금 신청에 계정·자산·네트워크·금액·목적지와 고유 client_request_id를 연결해 요청 전에 저장합니다. 생성 응답이 성공하면 withdrawal_id를 추가로 연결합니다.

client_request_id는 하나의 자금 이동 의도를 추적하며 내부이체와 외부 출금 전체에서 고유해야 합니다. 매 HTTP 요청의 HMAC nonce와는 목적이 다릅니다. 복구 조회에서는 같은 업무 요청 ID를 유지하면서 HTTP 인증 값은 새로 생성합니다.

3. 예약과 결과 조회

100 USDT를 보유한 고객이 20 USDT를 출금하고 수수료가 1 USDT라면, 접수 후에는 21 USDT가 예약되고 79 USDT를 사용할 수 있습니다. 이 시점의 총 잔액은 100 USDT이며 아직 출금 완료는 아닙니다.

상세 조회에서 다음 조건이 모두 충족돼야 외부 출금을 성공 처리합니다.

• request_type: EXTERNAL
• status: COMPLETED
• user_status: COMPLETED
• 유효한 tx_hash

다른 동시 거래가 없다면 완료 후 총 잔액은 79 USDT입니다. 실패·거절·취소로 예약이 해제되면 원금과 수수료의 복구를 최종 잔액으로 확인합니다. 자세한 금액 변화는 잔액과 원장을 참고합니다.

응답 유실과 취소

생성 응답이 유실돼 거래 ID를 받지 못했다면 GET /withdrawals/client-request/{client_request_id}로 기존 결과를 조회합니다. 타임아웃은 금융 거래 실패를 의미하지 않습니다. 한 번의 WITHDRAWAL_NOT_FOUND도 원본 요청의 미처리를 확정하지 않으므로 멱등성 가이드에 따라 복구합니다.

취소는 POST /withdrawals/{withdrawal_id}/cancel로 요청할 수 있으나 아직 취소 가능한 상태여야 합니다. 처리 단계에 따라 WITHDRAWAL_NOT_CANCELLABLE이 반환될 수 있습니다. 취소 요청을 보냈다는 사실만으로 종료하지 않고 API 결과와 잔액을 확인합니다.

계정 간 이체와 Digital Payment

일반 내부이체는 두 활성 계정 사이에서 같은 자산 유형의 자금을 이동합니다. 고객이 보유한 여러 계정 사이의 자금 이동이나 다른 사용자의 계정으로 보내는 서비스에 활용할 수 있습니다. 고객사 백엔드는 각 송신 계정과 작업에 대한 권한을 확인합니다.

Digital Payment에서는 송신 계정을 고객 USER, 수신 계정을 가맹점 BUSINESS로 두고 이체 거래를 주문에 연결합니다. 가맹점의 외부 정산은 위의 외부 출금 흐름을 그대로 사용합니다. 주문 ID나 정산 ID는 고객사 업무 식별자이고, withdrawal_id는 Wallet API의 자금 이동 식별자입니다.

고객 지갑의 실제 요청은 외부 출금 요청, 이후 조회는 출금 상태 추적에서 진행합니다. 상태별 처리 기준은 거래 상태 모델을 참고합니다.