.svg)
AI 솔루션 문의하기
1원 인증 API 연동 방법은 1원 송금 요청을 보내는 것보다, 인증코드를 어떻게 만들고 언제까지 유효하게 둘지, 고객이 입력한 코드를 어떤 규칙으로 검증할지를 먼저 정하는 데서 시작합니다. 송금 요청과 결과 수신은 제공사 문서를 따르면 되지만, 검증 규칙은 서비스가 직접 정해야 하고 이 규칙이 허술하면 코드를 맞히려는 반복 입력이나 이전 코드 재사용을 막을 수 없습니다. 이 글은 1원 인증 API를 연동하는 개발·기획 담당자가 인증 요청의 상태 관리, 인증코드 생성과 만료, 검증 규칙, 로그 저장을 어떻게 구현하는지 정리합니다. 송금 요청부터 재시도까지 전체 연동 단계는 계좌조회 API 연동 방법에서 다룹니다.
1원 인증은 송금 요청, 송금 완료, 코드 입력, 결과 확정까지 시간이 걸리는 과정이라, 인증 요청마다 지금 어느 단계에 있는지 상태를 저장해 두어야 합니다.
인증 요청 하나는 보통 요청 생성, 송금 요청, 송금 완료, 코드 입력 대기, 성공, 실패, 만료의 단계를 거칩니다. 각 단계를 상태 값으로 저장하고, 정해진 순서로만 바뀌게 하면 같은 요청이 두 번 성공 처리되거나 만료된 요청이 다시 성공으로 바뀌는 오류를 막을 수 있습니다.
인증 요청마다 고유번호를 만들고, 송금 요청과 코드 입력, 결과 저장을 모두 이 번호 아래 묶습니다. 제공사 쪽 요청 번호도 함께 저장해 두면, 송금 결과를 조회하거나 문의에 대응할 때 양쪽 기록을 바로 맞춰 볼 수 있습니다. 송금 응답이 늦어 결과를 받지 못했을 때도 같은 요청을 다시 보내지 말고, 이 번호로 처리 결과를 먼저 조회합니다.
고객이 버튼을 여러 번 누르거나 화면을 새로 열면 같은 계좌로 인증 요청이 동시에 여러 개 생길 수 있습니다. 같은 계정과 계좌에 진행 중인 요청이 있으면 새 송금을 보내지 않고 기존 요청의 입력 화면으로 돌려보내거나, 기존 요청을 만료시키고 하나만 남깁니다. 어느 쪽을 택하든 한 계좌에 동시에 살아 있는 요청은 하나뿐이어야 고객이 어떤 코드를 입력해야 할지 헷갈리지 않습니다.
인증코드는 고객이 은행 앱에서 보고 입력하기 쉬우면서, 다른 사람이 맞히기 어렵게 만들어야 합니다.
인증코드는 요청마다 서버에서 무작위로 만들고, 같은 고객에게 최근 보낸 코드와 겹치지 않게 합니다. 코드의 길이와 형식은 입금자명에 표시되는 글자 수 안에서 정하며, 비슷하게 생긴 글자는 빼서 입력 실수를 줄입니다. 코드를 직접 만들지 제공사가 만들어 주는지는 연동 문서에서 먼저 확인합니다.
서버에는 코드 원문 대신 비교에 필요한 형태로 저장하고, 화면이나 API 응답 값에는 코드를 내보내지 않습니다. 개발 중에 확인용으로 코드를 화면에 띄워 두었다가 운영에 그대로 남는 경우가 있으므로, 배포 전 점검 항목에 넣어 둡니다.
만료 시간은 요청을 만든 시점이 아니라 송금이 완료된 시점부터 계산해야 합니다. 송금이 늦게 반영되면 고객이 입금 내역을 보기도 전에 코드가 만료될 수 있기 때문입니다. 만료 시간이 지나면 상태를 만료로 바꾸고, 고객에게는 다시 보내기를 안내합니다. 만료 시간 값은 코드 여러 곳에 흩어 두지 말고 설정 한 곳에서 관리해야, 운영 중에 기준을 조정할 때 빠뜨리는 곳이 생기지 않습니다.
다시 보내기를 하면 새 코드로 새 송금을 보내고, 이전 코드는 즉시 쓸 수 없게 만듭니다. 여러 코드가 동시에 유효하면 고객이 예전 입금 건의 코드를 입력해도 통과되어, 시도 횟수 제한의 의미가 사라집니다.
검증 규칙은 정상 고객은 한 번에 통과하고, 맞히려는 시도는 빠르게 막히도록 정합니다.
고객이 입금자명을 통째로 복사해 붙여 넣으면 서비스 표시나 공백이 함께 들어옵니다. 비교 전에 앞뒤 공백을 지우고, 코드 형식에 맞는 부분만 골라내는 정리 규칙을 둡니다. 정리 규칙은 서버 한 곳에서만 적용해야, 화면마다 처리가 달라지는 문제가 생기지 않습니다.
입력한 코드를 비교하기 전에 요청 상태가 코드 입력 대기인지, 만료 시간이 지나지 않았는지 먼저 확인합니다. 상태가 맞을 때만 코드를 비교하고, 일치하면 상태를 성공으로 바꾼 뒤 같은 요청으로는 다시 성공 처리되지 않게 합니다. 성공 처리와 다음 단계(계좌 등록 완료, 정산 계좌 저장 등)는 한 번에 처리해, 성공으로 바뀌었는데 계좌가 저장되지 않는 상태가 남지 않게 합니다.
한 요청에 입력할 수 있는 횟수를 정하고, 넘기면 상태를 실패로 바꿔 새 요청을 받게 합니다. 계정 단위와 계좌 단위로도 일정 시간 동안의 요청 횟수를 제한하면, 여러 계좌를 번갈아 시도하는 경우까지 막을 수 있습니다.
코드 불일치, 만료, 횟수 초과, 송금 실패를 서로 다른 결과로 구분해 저장합니다. 고객에게는 이유에 맞는 안내를 보여주되, 코드가 몇 글자 맞았는지 같은 힌트는 주지 않습니다. 실패 이유별 비율은 이후 운영 지표의 기준이 되므로, 이유 값은 처음부터 정해진 목록 안에서만 쓰도록 합니다.
알체라 eKYC의 1원 인증은 고객 계좌로 1원을 송금한 뒤 입금 내역의 인증코드로 예금주 명의를 검증하며, 오픈뱅킹과 펌뱅킹 방식을 모두 지원하고 고객사 환경에 맞춘 API로 제공됩니다. 신분증 확인과 얼굴 매칭까지 같은 흐름으로 구성할 수 있어, 가입 단계의 본인 확인과 계좌 확인을 따로 연동하지 않아도 됩니다. 알체라 eKYC는 고객사 110곳, 누적 1,430만 회 인증, 제1금융권 70%가 사용하고 있습니다.
1원 인증 로그는 분쟁 대응과 이상 시도 탐지에 쓰이므로 필요한 것은 빠짐없이 남기되 민감한 값은 남기지 않고, 운영 전에는 예외 상황을 일부러 만들어 상태와 로그가 제대로 남는지 확인합니다.
요청 고유번호, 계정, 상태 변경 이력과 시각, 송금 결과, 입력 횟수, 최종 결과와 실패 이유를 남깁니다. 정산이나 환불 분쟁이 생겼을 때 어떤 계좌를 언제 인증했는지 바로 찾을 수 있게 계정과 연결해 둡니다.
계좌번호는 일부를 가려 저장하고, 인증코드 원문과 고객이 입력한 값은 로그에 남기지 않습니다. 운영자가 로그를 조회하는 권한도 필요한 담당자로만 제한하고, 누가 언제 조회했는지도 함께 기록합니다.
로그 보관 기간을 정하고, 지나면 자동으로 지우도록 설정합니다. 업무상 오래 보관해야 하는 기록과 짧게 두어도 되는 기록을 나눠 두면 기준을 지키기 쉽습니다.
운영에 적용하기 전에 다음 상황을 일부러 만들어 확인합니다. 실제 송금 없이 결과를 시험할 수 있는 테스트 환경이 있는지도 제공사에 먼저 확인합니다.
운영을 시작한 뒤에는 송금 완료 대비 성공 비율, 실패 이유별 비율, 다시 보내기 비율을 주기적으로 보고, 실패가 몰리는 단계부터 규칙과 안내를 조정합니다. 연동 문서에 없는 응답이 오면 시스템 실패로 분류해 기록하고 알림을 받도록 해 둡니다. 특정 은행에서만 송금 실패나 만료가 몰린다면 그 은행의 입금 반영 시간이나 점검 시간을 확인하고, 해당 은행 고객에게만 안내 문구를 다르게 보여주는 방법도 검토합니다.
.png)
.svg)
.svg)
