Tovanix

신원 및 거래 위험 검증 API

플랫폼 API 키로 자체 시스템에서 개인 인증(KYC), 기업 인증(KYB), 거래 모니터링, 지갑 주소 스크리닝을 시작하고 검사 기록을 조회합니다. 오픈 API와 콘솔은 같은 검사 절차를 거치므로 단가가 같고, 결과·환불·대사 규칙도 같습니다.

먼저 콘솔의 「신원 및 거래 위험 검증」에서 「개통」을 누른 다음, 「API 관리」에서 키를 만들고 「검증 및 리스크」 권한을 선택하세요. 단가와 기록 조회에는 verification.read, 검사 시작에는 verification.write 권한이 필요합니다. 검사를 시작하면 건당 계정 잔액에서 차감됩니다.

엔드포인트

GET /api/v1/verification/info: 이 계정의 개통 여부, 네 가지 검사 유형별 제공 여부와 단가(USD), 거래 모니터링과 지갑 스크리닝에서 선택할 수 있는 네트워크와 자산을 반환합니다. 제공되지 않는 유형에는 단가가 표시되지 않습니다.
POST /api/v1/verification/checks: 검사를 한 번 시작합니다. 과금과 기록 생성은 같은 요청 안에서 처리됩니다. 신원 인증은 handoff_url 필드로 인계 링크를 반환하며, 이 링크를 피인증자에게 보내면 됩니다. 거래 모니터링과 지갑 스크리닝은 대개 결과를 바로 반환합니다.
GET /api/v1/verification/checks: 목록은 시작 시간의 역순이며, kind, status, verdict, keyword(번호 / 주소 / 결제 번호) 필터와 page, page_size 페이지 나누기(페이지당 최대 100건)를 지원합니다. 단건 조회는 세션이 아직 피인증자 쪽에 있을 때 handoff_url 필드도 함께 반환합니다. 새로고침은 서비스 제공자에서 결과를 다시 읽어 옵니다(지갑 스크리닝은 새로고침할 수 없으며, 다시 조회하면 다시 과금됩니다).

idempotency_key 값과 내용이 모두 같은 재시도에는 원래 기록을 반환하며 다시 과금하지 않습니다. 같은 키로 내용을 바꾸면 거부됩니다(400). 같은 대상 번호로 아직 완료되지 않은 신원 인증을 다시 시작하면 기존 세션을 반환하며(reused 값은 true), 이때도 과금하지 않습니다.

결과 콜백

콘솔의 「연동 설정」에서 https 콜백 주소를 입력하고 사용으로 설정하세요. 검사 기록의 상태나 결과가 비동기로 바뀌면(신원 인증 완료, 수동 검토로 결과 변경, 거래 결과 업데이트, 실패 후 환불) 플랫폼이 이벤트 하나를 POST합니다. 직접 시작한 요청 자체는 푸시하지 않습니다. 동기 응답에 이미 결과가 들어 있기 때문입니다.

요청 헤더 중 X-Tovanix-Event 헤더는 이벤트 유형(check.updated 또는 테스트용 ping), X-Tovanix-Delivery 헤더는 event_id, X-Tovanix-Timestamp 헤더는 Unix 시간(초), X-Tovanix-Signature 헤더는 sha256= 뒤에 HMAC-SHA256(서명 키, 타임스탬프 + "." + 원본 요청 본문)의 hex 문자열을 붙인 값입니다.

상대방이 2xx 응답을 반환하면 전달된 것으로 봅니다. 그 밖의 경우(타임아웃 포함)는 1분, 5분, 15분, 1시간, 3시간, 6시간, 12시간 간격으로 백오프하며 최대 8회까지 보내고, 그 뒤로는 보내지 않습니다. 재시도에는 같은 event_id 값과 같은 이벤트 본문이 담기므로 event_id 기준으로 중복을 제거하세요. 이벤트는 순서가 바뀌어 도착할 수 있습니다. data.updated_at 값이 더 최근인 쪽을 기준으로 하거나, 받은 뒤 조회 API를 호출해 최신 상태를 가져오세요. 콜백을 끄면 아직 전달되지 않은 이벤트는 더 이상 보내지 않습니다.

불러오는 중…