원화 기준 출금 · 빗썸 시세 환산 · BSC 단일 체인 락업 · 출금팀 처리 체계
| 구분 | 항목 | 확정 내용 |
|---|---|---|
| 금액 · 환율 | 금액 기준 | 원화(KRW) — 유저는 신청액 전액 수령 (차감 없음) |
| 환율 | 신청 순간 빗썸 USDT 가격 각인 · 직전 대비 ±5% 초과 시 접수 거절 | |
| 소수점 | 6자리 · 락업액은 올림(ceil) · dust는 파트너 원복 | |
| 출금 한도 | 단건 20만 ~ 500만원 | |
| 락업 | 락업 시점 | 출금팀이 [승인] 누를 때 (신청 시 아님) |
| 체인 | BSC(BEP-20) 메인 · 자동 잔액 검증 후 단일 체인, 분할 없음 | |
| 동시성 | 파트너 × 체인 비관적 락으로 동시 승인 직렬화 | |
| 잔액 부족 | 오더 유지 + ⚠표시 + 파트너 충전 알림 → 충전 후 재승인 | |
| 오더 | 유효시간 | 1시간 — 초과 시 자동 만료 (락업 전이라 원복 불필요) |
| 정렬 | 접수순(FIFO) 기본 | |
| 상태 | 6종 — 요청중 · 승인 · 확인완료 · 출금중 · 완료 · 반송 | |
| 출금팀 | 구성 | 1팀 · 주야간 교대 · 정산은 팀 단일 계정 |
| 처리 방식 | 전 구간 단독 처리 (2인 확인 없음) | |
| 지급 타이머 | 20만~100만 : 30분 / 60분 · 100만~500만 : 60분 / 120분 | |
| 보고 | 증빙(이체확인증/거래번호) 필수 + 계좌 뒷4자리 대조 | |
| 정산 | 수수료 | 파트너별 요율 필드 (기본 1% = 크립토먼츠 0.5% + 출금팀 0.5%) · 파트너 부담 |
| 처리 | 원자적 3분할 (전부 or 전무) · 건별 즉시 내부 적립 | |
| 인출 홀드 | 정산 후 24시간 인출 불가 — 반송 대비 회수 재원 | |
| 가스비 | 인출 시 크립토먼츠 부담 (기존 Relayer 대납 재사용) | |
| 채널 | 정보 분리 | API = 사유 코드만 / 잔액·내역은 관리페이지 + 텔레그램 |
| 텔레그램 | 출금팀 단톡방 + 파트너별 개별 채널 | |
| 제외 | 범위 밖 | LP 출금담당 ❌ · eKYC ❌ (별도 트랙) · 오더 선점락 ❌ (팀 내부 운영) |
| 주체 | 내주는 것 | 받는 것 | 접점 |
|---|---|---|---|
| 파트너사 2개 → 확장 | USDT (승인 시 락업) | 유저 출금 대행 완료 | 신청·조회 API / webhook / 관리페이지 / 텔레그램 |
| 유저(수취인) | — | 원화 신청액 전액 | 은행 계좌 |
| 출금팀 1팀 · 주야간 | 유저에게 원화 지급 | USDT + 0.5% (팀 계정) | 출금팀 오더 페이지 + 텔레그램 단톡방 |
| 크립토먼츠 | 중개 · 환산 · 정산 · 회수 협조 | 수수료 0.5% | 시스템 · 운영자 콘솔 |
원화 신청액 ÷ 빗썸 시세 = 락업 USDT · 유저는 1,000,000원 전액 수령, 수수료는 파트너 부담
올림(ceil)을 쓰는 이유 — 내림하면 정산 시 극소량이 모자라 분배가 실패할 수 있다. 올림하면 파트너가 아주 조금 더 내지만 절대 부족하지 않다.
dust(잔여분) — 정산 시 실제 분배액만 소멸시키고, 남은 극소량은 파트너 available로 원복한다.
| 구간 | 승인 후 경고 | 에스컬레이션 | 비고 |
|---|---|---|---|
| 20만 ~ 100만 미만 | 30분 | 60분 | 단독 처리 |
| 100만 ~ 500만 | 60분 | 120분 | 은행 지연인출제도(100만↑ 30분 출금제한) 반영 |
| 20만 미만 / 500만 초과 | 접수 거절 — 사유 코드 AMOUNT_OUT_OF_RANGE | ||
| 상태 | 진입 시점 | 락 | 다음 |
|---|---|---|---|
| 요청중 | 오더 생성 (락업 전) · 잔액 부족 시 유지 | 🔓 없음 | 승인 / 1시간 만료 / 취소 |
| 승인 | 잔액 검증 통과 + 락업 | 🔒 설정 | 확인완료 / 실패 (파트너 취소 차단) |
| 확인완료 | 지급 확인 + 증빙 + 뒷4자리 일치 | 🔒 유지 | 출금중 |
| 출금중 | 정산·분배 진행 (원자적) | 🔓 해제 중 | 완료 / 실패 |
| 완료 | 파트너 webhook 반환 | — | 반송 (사후 발생 가능) |
| 반송 | 이체 반송 확인 → 운영자 역정산 | ↩️ 파트너 복구 | (종결) |
| 실패 | 만료 · 취소 · 확인실패 · 정산실패 | ↩️ 원복 (락업 후만) | (종결) |
| 시점 | 전환 | 파트너 USDT |
|---|---|---|
| [5] 승인 | 🔒 설정 | available → locked (단일 체인) |
| [9] 정산 | ✅ 소멸 | locked → 출금팀 + 시스템 · dust 원복 |
| 실패 · 취소 | ↩️ 원복 | locked → available (동일 체인) |
| 반송(사후) | ↩️ 역정산 | 출금팀·시스템 회수 → 파트너 복구 |
요청중 단계엔 락이 없다 — 만료돼도 원복할 자금이 없어 부담 0. 이것이 락업을 승인 시점으로 옮긴 가장 큰 이점.
| 지점 | 시간 | 동작 |
|---|---|---|
| 요청중 방치 | 1시간 | 자동 만료 → 실패 반환 (락 없음) |
| 승인 후 미지급 (20만~100만) | 30분 / 60분 | 경고 → 관리자 에스컬레이션 |
| 승인 후 미지급 (100만~500만) | 60분 / 120분 | 지연인출제도 반영 |
| 정산 후 인출 | 홀드 24시간 | 반송 대비 회수 재원 확보 |
락이 걸린 구간엔 자동 실패가 없다 — 돈이 이미 나갔을 수 있어 모든 종결은 사람이 확인 후 처리.
| 계층 | 방어 | 내용 |
|---|---|---|
| 프론트 | 버튼 즉시 비활성 | 연타 차단 |
| API | 멱등키(report_id) | 재시도 시 기존 결과 반환 — 에러로 던지지 않는다 (또 누르게 됨) |
| 상태 가드 | 현재 상태 확인 후 전이 | 승인=요청중일 때만 / 보고=승인일 때만 / 정산=확인완료일 때만 |
같은 원리로 승인 중복(락업 2회) · 정산 중복(USDT 2회 분배) 까지 동시에 차단된다.
| 단계 | 내용 |
|---|---|
| 수기 입력 제거 | 오더 화면의 계좌·금액에 [복사] 버튼 — 손으로 옮겨적지 않게 |
| 보고 시 대조 | 송금한 계좌 뒷 4자리 입력 → 오더 계좌와 자동 대조 → 불일치 시 보고 차단 |
| 발생 시 처리 | 오더는 【승인】(미지급) 유지 → 올바른 계좌로 재송금 → 정상 보고 → 정산 |
| 책임 | 출금팀 과실 (계약·약관 명시) — 파트너·유저는 피해 없음 |
| 회수 | 크립토먼츠는 오프라인 회수 협조 (착오송금 반환지원제도 안내 · 증빙 정리 · 수취인 접촉 협조). 회수 진행은 시스템 밖 트랙 — 오더에 incident_note 메모만 남긴다 (회수 성패가 오더 처리를 막지 않게) |
| 유형 | 처리 |
|---|---|
| 즉시 거부 (계좌번호 오류 등) | 송금 자체가 안 됨 → 보고 없음 → 지급 실패로 오더 종결 + 락 원복. 문제 없음 |
| 지연 반송 ⚠ (지급정지·해지 계좌) | 정산까지 끝난 뒤 며칠 후 반송 → 운영자 [반송 처리] · 출금팀 잔액에서 USDT + 0.5% 회수· 크립토먼츠 수수료 0.5% 회수· 파트너 available 전액 복구 → 상태 【반송】 |
| 전제 조건 | 정산 후 인출 홀드 24시간 — 홀드가 없으면 출금팀이 바로 인출해버려 회수할 재원이 없다 |
| 권한 | 역정산은 운영자만 실행 가능 |
| 항목 | 내용 |
|---|---|
| 원자성 | 락업+상태전이 / 정산 3분할을 각각 하나의 트랜잭션으로. 실패 시 전부 롤백 후 재시도 |
| 일일 대사 | 일 1회 배치 — 파트너 잔액 변동 = 정산 합계 대조, 불일치 시 알림. 조용한 오차를 잡는 유일한 수단 |
| 연타 차단 | 60초 내 동일 (유저 + 계좌 + 금액) 중복 신청 차단 |
| 한도 | 파트너별 일일 총액 · 유저별 일일 건수/금액 (설정값) — 사고 시 피해 상한 |
| 접근 통제 | 오더 페이지 IP 화이트리스트 + 계정 로그인 + 승인 시 2FA(OTP) |
| 권한 분리 | 조회 / 승인 / 보고 / 운영자(취소·역정산) — 역정산은 운영자 전용 |
| 개인정보 | 계좌·예금주 목록 마스킹(상세만 전체) · 접근 로그 · 보관기간 설정 · 증빙 저장소 접근 통제 |
| 필드 | 내용 | 비고 |
|---|---|---|
partner_id | 파트너 구분 | 2개 → 확장 |
order_id | 파트너 고유 주문번호 | 멱등키 |
user_id | 파트너 회원 식별자 | 유저 한도 산정 |
krw_amount | 신청 원화액 = 유저 수령액 | 20만 ~ 500만 |
rate_krw / rate_at | 신청 순간 빗썸 시세 + 조회 시각 | 각인 — 변동 무관 · 분쟁 근거 |
usdt_amount | 환산 USDT (6자리 올림) | 출금팀 정산 원금 |
fee_rate / fee_amount | 파트너별 요율 + 수수료액 | 기본 1% |
chain | 락업된 단일 체인 | 원복도 동일 체인 |
locked_amount / locked_at | 락업 총액 · 승인 시각 | dust 계산 기준 |
expire_at | 접수 + 1시간 | 자동 만료 |
bank / account / holder | 수취 은행 · 계좌 · 예금주 | 개인정보 — 마스킹 |
approver_id | 승인·처리한 근무자 | 감사 추적 |
paid_account_last4 | 실제 송금 계좌 뒷 4자리 | 대조 근거 |
proof | 이체확인증 · 거래번호 | 보고 시 필수 |
report_id | 보고 멱등키 | 중복 보고 차단 |
settled_at / hold_until | 정산 시각 · 인출 가능 시각 | 홀드 24h |
reversed_at / reverse_reason | 역정산 시각 · 사유 | 반송 처리 |
fail_reason | 실패 사유 코드 | 파트너 자동 분기용 |
incident_note | 사고 경위 메모 | 오송금 등 — 운영자 입력 |
파트너별 요율 필드로 설계 (기본 1%) — 파트너가 늘면 협상 요율이 생기므로 처음부터 필드로 두어야 나중에 정산 로직을 뜯지 않는다.
유저는 신청 원화액 전액 수령 · 출금팀 수익은 건별 즉시 내부 적립 · 인출 가스비는 크립토먼츠 부담.
| 오더 | 파트너 | 원화액 | 필요 USDT | 체인 | 상태 |
|---|---|---|---|---|---|
| #101 | A사 | 1,000,000 | 706.29 | BSC | 요청중 |
| #102 | B사 | 500,000 | 353.15 | BSC | 요청중 |
| #103 | A사 | 800,000 | 565.03 | — | ⚠ 잔액부족 141 USDT |
오더 상세 : 계좌·금액 [복사] 버튼 · 예금주명 강조 · 승인 시 남는 잔액 미리보기 · 경과시간 표시
| 체인 | 가용 | 락업중 | 합계 |
|---|---|---|---|
| BSC | 494.00 | 706.29 | 1,200.29 |
동일 내용이 파트너 텔레그램 채널로도 즉시 발송된다. API로는 내려주지 않는다.
모든 수치를 설정으로 뺀다 — 운영이 코드 수정 없이 조정할 수 있어야 실제 운영에서 살아남는다.
| 구간 | 케이스 | 처리 | 상태 |
|---|---|---|---|
| A 신청 | 중복 order_id | 멱등 — 기존 오더 반환 | ✅ |
| 필수정보 누락 / 정책 위반 | 거절 (사유 코드) | ✅ | |
| 금액 20만 미만 / 500만 초과 | 거절 AMOUNT_OUT_OF_RANGE | ✅ | |
| 빗썸 시세 조회 실패 | 5분 캐시 허용, 초과 시 거절 · 임의 추정 금지 | ✅ | |
| 시세 이상치(스파이크) | 직전 대비 ±5% 초과 시 거절 + 알림 | ✅ | |
| 점검시간 / 접수중지 | SERVICE_CLOSED 거절 | ✅ | |
| 동일 유저·계좌·금액 연타 | 60초 창 내 중복 차단 | ✅ | |
| B 대기 | 1시간 미승인 | 자동 만료 (락 없어 부담 0) · 30분 시점 리마인드 | ✅ |
| 파트너 취소 | 즉시 실패 (요청중일 때만 가능) | ✅ | |
| 파트너 계약 정지 | 신규 접수만 차단, 진행 중 오더는 정상 완주 | ✅ | |
| C 승인·락업 | 잔액 충족 | 락업 → 승인 · chain 각인 | ✅ |
| 잔액 부족 | 오더 유지 + ⚠부족액 표시 + 파트너 충전 알림 | ✅ | |
| 동시 승인 경합 | 파트너×체인 비관적 락으로 직렬화 | ✅ | |
| 단일 체인 부족 / 타 체인 충분 | 그 체인으로 락업 · 화면에 체인 표시 | ✅ | |
| 승인 중복 클릭 | 상태 가드 — 요청중일 때만 접수 | ✅ | |
| D 지급 | 승인 후 방치 | 금액대별 경고 → 에스컬 → 수동 종결 | ✅ |
| 다른 계좌로 이체 | 뒷4자리 대조로 보고 차단 → 미지급 유지 → 재송금 · 출금팀 책임 + 회수 협조 | ✅ | |
| 이체 금액 불일치 | 정산 보류 → 차액 이체 or 수동 실패. 자동 정산 금지 | ✅ | |
| 출금팀 원화 소진 | 팀 자체 판단(승인 안 함) + 화면에 대기 원화 총액 표시 | ✅ | |
| 중복 보고 | 멱등 3중 방어 — 기존 결과 반환 | ✅ | |
| E 확인·정산 | 정상 확인 | 정산 진행 | ✅ |
| 유저 미수령 신고 | 보류(HOLD) + 운영자 중재 · 자동 판정 금지 | ✅ | |
| 이체 반송 | 즉시거부=지급실패 종결 / 지연반송=역정산 (홀드 24h가 재원) | ✅ | |
| 정산 중 장애 | 원자적 트랜잭션 롤백 → 확인완료로 복귀 · 정체 감지 알림 + 재개 | ✅ | |
| F 연동·운영 | webhook 유실 | 조회 API가 정본 — 연동문서에 명시 | ✅ |
| 텔레그램 발송 실패 | 재시도 + 페이지 폴링으로 보완 | ✅ | |
| 파트너 USDT 충전 | 기존 입금 플로우 재사용 · confirm 지연은 관리페이지에 “확인 중” 표시 | ✅ |
1. 소수점·반올림 — 무한소수 절사 정책 부재 → 정산 부족 위험
2. 파트너 USDT 충전 경로 — "충전하세요" 만 있고 방법이 없었음
3. 정산 원자성 — 3분할 중 일부만 반영되면 장부 붕괴
4. 락업–상태 원자성 — 락업 성공 + 상태 실패 = 유령 락업
5. 출금팀 허위 보고 — 안 보내고 보고만 할 위험
| 원칙 | 적용 |
|---|---|
| ① 애매하면 사람이 판단 | 분쟁·미수령·금액 불일치·이상거래는 자동 판정 금지 — 오판 비용이 훨씬 크다 |
| ② 숫자는 시스템이, 실행은 사람이 | 환율·원화액·필요 USDT를 시스템이 확정 → 출금팀은 표시된 금액을 그대로 이체 |
| ③ 값은 전부 설정으로 | 시간·한도·요율·임계 — 코드 수정 없이 운영이 조정 |
| ④ 기존 것 재사용 | 시세 동기화 · 텔레그램 봇 · 입금/출금 플로우 · 상태이력 · Relayer 대납 |
| ⑤ 락은 필요한 순간에만 | 승인 시점 락업 — 요청중엔 자금을 묶지 않아 만료돼도 손해가 없다 |
| ⑥ 자동 실패는 락 없는 구간에만 | 1시간 만료(락 없음)는 자동, 승인 이후는 전부 사람이 종결 |
| 단계 | 내용 |
|---|---|
| 1. 기술 설계 | DDL(오더/정산/설정 테이블) · API 스펙(신청·조회·webhook·사유코드) · 상태머신 구현 명세 |
| 2. 화면 설계 | 출금팀 오더 페이지 · 파트너 관리 페이지 · 운영자 콘솔(취소·역정산·대사) |
| 3. 연동 문서 | 파트너 API 가이드 — 조회가 정본 명시 · 사유 코드 표 · 텔레그램 채널 등록 절차 |
| 4. 운영 준비 | 약관·계약 (실명확인 파트너 책임 / 오송금 출금팀 책임) · 설정 초기값 · 대사 절차 |