외부 주소로 정산·지급

외부 정산은 가맹점 결제 계정에 모인 자금을 선택한 네트워크의 외부 주소로 보냅니다. OOLIN이 요청을 검증하고 온체인 전송을 처리한 뒤 최종 결과를 Wallet API에 반영하는 비동기 처리입니다.

고객 백엔드 → 외부 출금 생성 → 요청 처리
  → 온체인 전송 → Wallet API 결과 조회

고객 백엔드는 Wallet API로 출금을 생성하고 상세 조회로 최종 결과를 확인합니다.

외부 주소 검증과 견적 요청

올바른 Sepolia 외부 주소를 사용합니다. 다른 OOLIN 계정의 입금 주소를 지정하면 내부이체로 분류될 수 있습니다.

export TO_ADDRESS='{valid-testnet-address}'
export WITHDRAW_AMOUNT='1.00'

asset_response="$(
  wallet_request GET "/assets/by-type-network?asset_type_id=$ASSET_TYPE_ID&network_id=$NETWORK_ID"
)"
export ASSET_ID="$(printf '%s' "$asset_response" | jq -r '.data.asset_id')"

validate_body="$(jq -nc --arg address "$TO_ADDRESS" '{address:$address}')"
wallet_request POST "/assets/$ASSET_ID/validate-address" "$validate_body" | jq

data.is_valid가 true이면 견적을 요청합니다.

quote_body="$(jq -nc \
  --argjson account_id "$PAYMENT_ACCOUNT_ID" \
  --argjson asset_type_id "$ASSET_TYPE_ID" \
  --arg amount "$WITHDRAW_AMOUNT" \
  --arg to_address "$TO_ADDRESS" \
  --argjson network_id "$NETWORK_ID" \
  '{account_id:$account_id,asset_type_id:$asset_type_id,amount:$amount,to_address:$to_address,network_id:$network_id}')"

wallet_request POST '/withdrawals/quote' "$quote_body" | jq

can_withdraw가 true이고 transfer_type이 EXTERNAL일 때만 진행합니다. 수수료, 수령 금액, 최소·최대 한도도 확인합니다.

계정에서 예약·차감되는 금액은 amount + fee_amount이며 receive_amount는 수취 금액입니다. 견적은 잔액 예약이나 출금 성공을 보장하지 않으므로 생성 시 오류도 처리해야 합니다.

외부 출금 생성

SETTLEMENT_REQUEST_ID를 정산 업무·금액·목적지와 연결해 요청 전 영구 저장합니다. 복구할 때는 저장한 ID를 사용하며 같은 정산에 새 ID를 만들지 않습니다.

export SETTLEMENT_REQUEST_ID="settlement-$(node -e 'process.stdout.write(require("crypto").randomUUID())')"

withdrawal_body="$(jq -nc \
  --argjson account_id "$PAYMENT_ACCOUNT_ID" \
  --argjson asset_type_id "$ASSET_TYPE_ID" \
  --arg amount "$WITHDRAW_AMOUNT" \
  --arg to_address "$TO_ADDRESS" \
  --argjson network_id "$NETWORK_ID" \
  --arg client_request_id "$SETTLEMENT_REQUEST_ID" \
  '{account_id:$account_id,asset_type_id:$asset_type_id,amount:$amount,to_address:$to_address,network_id:$network_id,client_request_id:$client_request_id}')"

withdrawal_response="$(wallet_request POST '/withdrawals' "$withdrawal_body")"
export WITHDRAWAL_ID="$(printf '%s' "$withdrawal_response" | jq -r '.data.withdrawal_id')"
printf '%s\n' "$withdrawal_response" | jq

응답의 request_type이 EXTERNAL인지 확인합니다. 생성 시 출금액과 수수료가 pending_withdraw_amount_raw에 예약되지만 온체인 출금이 완료된 것은 아닙니다.

생성 응답이 유실되면 다음 조회로 복구하고 반환된 withdrawal_id를 WITHDRAWAL_ID에 저장합니다. 한 번의 WITHDRAWAL_NOT_FOUND로 미처리를 확정하지 않으며 자세한 정책은 멱등성 가이드를 따릅니다.

wallet_request GET "/withdrawals/client-request/$SETTLEMENT_REQUEST_ID" | jq

최종 결과 추적

wallet_request GET "/withdrawals/$WITHDRAWAL_ID" | jq

user_status	의미	고객 백엔드 처리
PENDING	요청 접수 및 검사	제한된 주기로 조회
PROCESSING	승인 또는 온체인 전송 처리	정산 대기 상태 유지
COMPLETED	온체인 출금 완료	tx_hash, completed_at 저장
FAILED	온체인 처리 실패	실패 기록과 잔액 복구 확인
REJECTED	처리 거절	사유 기록과 운영 대응
CANCELLED	요청 취소	요청 종료와 잔액 확인

최종 성공은 user_status: "COMPLETED", status: "COMPLETED", 유효한 tx_hash를 모두 확인해야 합니다.

다음: 자금 집금과 회수