계좌조회 API 연동 방법은 계좌에서 무엇을 확인하려는지에 따라 달라지며, 고객이 등록한 계좌가 본인 것인지 확인하는 것이 목적이라면 1원 인증을 기준으로 연동 흐름을 설계합니다. 1원 인증 연동은 1원 송금 요청, 인증 코드 입력, 결과 처리, 실패 시 재시도의 네 단계로 이루어집니다. 각 단계에서 무엇을 저장하고 어떤 실패를 어떻게 처리할지 미리 정해 두면, 운영 중에 생기는 문의와 수작업을 줄일 수 있습니다.
알체라 eKYC는 1원 인증을 API로 제공해, 계좌 등록·환불 계좌 등록·대출금 지급 계좌 확인 단계에 그대로 붙일 수 있습니다. 알체라 eKYC는 고객사 110곳, 누적 1,430만 회 인증, 제1금융권 70%가 사용하고 있습니다.
1원 인증 연동 전에 무엇을 준비하나요?
1원 인증 연동을 시작하기 전에 다음 여섯 가지를 정해 두면 개발 중에 다시 설계하는 일이 줄어듭니다.
API 키 발급과 보관: 제공사에서 API 키를 받아 서버에만 보관합니다. 앱이나 웹 화면 코드에 키를 넣으면 외부에 노출될 수 있습니다.
테스트·운영 환경 분리: 테스트용과 운영용 요청 주소(엔드포인트)와 키를 나눠 관리해, 테스트 요청이 실제 계좌로 나가지 않게 합니다.
암호화된 통신: 모든 요청은 HTTPS로 보내 계좌번호와 실명 정보가 전송 중에 노출되지 않게 합니다. 토큰 방식 인증을 쓰는 경우 토큰 만료와 갱신 처리도 함께 준비합니다.
인증 코드 정책: 인증 코드를 입력할 수 있는 유효 시간, 코드 재입력 허용 횟수, 1원 다시 보내기 허용 횟수를 정합니다.
고객 동의 문구: 어떤 목적으로 계좌를 확인하는지, 1원이 입금된다는 점을 고객에게 알리는 문구를 정합니다.
결과 저장 기준: 계좌번호는 일부를 가려 저장하고, 요청 고유번호, 결과, 실패 사유, 일시를 기록하기로 정합니다.
1단계: 1원 송금 요청은 어떻게 보내나요?
1원 송금 요청은 고객이 입력한 계좌로 1원과 인증 코드를 보내 달라고 요청하는 단계입니다. 요청에는 보통 은행 코드, 계좌번호, 고객 이름 같은 확인 정보가 들어가고, 응답으로 요청을 구분하는 고유번호와 처리 결과가 돌아옵니다. 구체적인 항목 이름과 형식은 제공사의 연동 문서를 따릅니다.
이 단계에서 구현할 때 주의할 점은 다음과 같습니다.
명의 대조를 먼저: 1원을 보내기 전에 계좌 명의가 고객과 같은지 확인하면, 다른 사람 명의 계좌에 불필요한 송금을 보내지 않습니다.
요청 고유번호 저장: 응답으로 받은 고유번호를 고객 계정과 함께 저장해, 이후 인증 코드 확인과 결과 조회에 씁니다.
중복 요청 방지: 고객이 버튼을 여러 번 누르거나 네트워크가 끊겨 같은 요청이 두 번 나가지 않도록, 진행 중인 요청이 있으면 새 요청을 막습니다.
송금 실패 응답 구분: 계좌 없음, 해지 계좌, 은행 점검처럼 송금 자체가 실패한 경우는 인증 코드 입력 화면으로 넘기지 않고 바로 안내합니다.
2단계: 인증 코드 입력은 어떻게 받나요?
인증 코드 입력은 고객이 은행 앱에서 1원 입금 건의 입금자명을 확인하고, 그 안의 코드를 서비스 화면에 입력하는 단계입니다. 고객이 앱을 오가야 해서 이탈이 생기기 쉬우므로 화면 안내가 중요합니다.
어디를 보면 되는지 안내: "은행 앱의 입출금 내역에서 1원 입금 건의 입금자명을 확인해 주세요"처럼 구체적으로 알려줍니다.
남은 시간 표시: 정한 유효 시간 안에서 남은 시간을 화면에 보여줍니다.
입력값 정리: 고객이 앞뒤 공백을 넣거나 대소문자를 섞어 입력해도 같은 코드로 처리할지 정해, 서버에서 비교하기 전에 입력값을 정리합니다.
다시 보내기 버튼: 입금이 보이지 않는 고객을 위해 일정 시간이 지나면 다시 보내기를 누를 수 있게 합니다.
3단계: 인증 결과는 어떻게 처리하나요?
인증 결과 처리는 고객이 입력한 코드가 맞는지 서버에서 확인하고, 결과에 따라 계좌를 확정하거나 실패를 안내하는 단계입니다.
서버에서 확인: 코드 비교는 반드시 서버에서 합니다. 화면 코드에서 비교하면 정답 코드가 노출될 수 있습니다.
성공 시 계좌 확정: 코드가 맞으면 해당 계좌를 고객의 확인된 계좌로 저장하고, 확인 일시를 함께 남깁니다.
실패 시 사유 기록: 코드 불일치, 시간 초과 등 실패 사유를 나눠 기록하고 4단계의 재시도 흐름으로 넘깁니다.
다음 업무와 연결: 정산·환불·대출금 지급 업무에서는 확인된 계좌로만 돈이 나가도록, 지급 단계에서 확인 여부를 다시 조회합니다.
4단계: 실패하면 어떻게 다시 시도하게 하나요?
실패 처리는 실패 유형마다 다르게 해야 정상 고객은 다시 시도해 통과하고, 반복 시도는 막을 수 있습니다.
코드 불일치: 같은 1원 입금 건으로 정해진 횟수까지 다시 입력하게 합니다. 횟수를 넘으면 새 코드로 다시 보내기를 안내합니다.
시간 초과: 기존 코드는 무효로 처리하고 다시 보내기를 안내합니다.
송금 실패: 계좌 정보가 잘못됐다면 계좌를 다시 입력하게 하고, 은행 점검이라면 잠시 후 다시 시도하라고 안내합니다.
응답 지연·네트워크 오류: 바로 새 요청을 보내지 말고, 저장해 둔 요청 고유번호로 처리 결과를 먼저 조회합니다. 결과를 확인하지 않고 다시 보내면 1원이 두 번 입금될 수 있습니다.
인증 오류: API 키나 토큰 문제라면 고객에게는 일시 오류로 안내하고, 내부적으로 키와 토큰 상태를 점검합니다.
다시 보내기는 계정과 계좌 기준으로 하루 허용 횟수를 정해 두고, 이를 넘으면 담당자 확인으로 넘기는 것이 좋습니다. 같은 계좌로 인증을 계속 시도하는 경우를 막을 수 있습니다.
계좌를 바꾸거나 다시 확인해야 할 때는 어떻게 처리하나요?
1원 인증으로 확인한 계좌도 고객이 계좌를 바꾸거나 오랫동안 쓰지 않았다면 다시 확인하는 기준이 필요합니다. 다음 기준을 연동 범위에 함께 넣어 두는 것이 좋습니다.
계좌 변경: 고객이 지급 계좌를 바꾸면 기존 확인 결과를 쓰지 않고 1단계부터 다시 진행합니다. 계좌를 바꾼 직후 큰 금액이 나가는 경우가 있어 이 기준을 생략하지 않습니다.
확인 결과 유효 기준: 확인한 지 오래된 계좌로 큰 금액을 지급할 때 다시 확인할지 내부 기준을 정합니다.
여러 계좌 등록: 한 고객이 여러 계좌를 등록할 수 있다면 계좌마다 따로 확인하고, 어떤 계좌가 확인됐는지 화면에 표시합니다.
확인 이력 조회: 고객지원 담당자가 고객 문의를 받았을 때 언제, 어떤 계좌로, 어떤 결과가 나왔는지 바로 볼 수 있게 관리 화면을 만듭니다.
테스트 환경에서는 무엇을 점검해야 하나요?
운영에 적용하기 전에 테스트 환경에서 다음 상황을 일부러 만들어, 화면 안내와 기록이 제대로 남는지 확인합니다.
정상 계좌로 1원 인증을 끝까지 성공하는 경우
명의가 다른 계좌를 입력해 1원 송금 전에 걸러지는 경우
인증 코드를 틀리게 입력해 재입력 횟수를 모두 쓰는 경우
유효 시간이 지나 다시 보내기를 하는 경우
응답이 늦게 와서 결과 조회로 처리하는 경우
같은 계좌로 다시 보내기를 허용 횟수 이상 시도하는 경우
운영 중에는 무엇을 확인해야 하나요?
연동 후에는 다음 지표를 주기적으로 보면 문제가 생긴 단계를 빨리 찾을 수 있습니다.
단계별 완료율: 계좌 입력, 1원 송금, 코드 입력 중 어디에서 고객이 많이 멈추는지 봅니다.
실패 사유 비율: 코드 불일치가 많으면 화면 안내를, 송금 실패가 많으면 계좌 입력 화면을 먼저 고칩니다.
다시 보내기 비율: 다시 보내기가 많으면 고객이 입금자명을 찾기 어렵다는 뜻이므로 안내 문구를 고칩니다.
정리: 계좌조회 API 연동 순서
고객 계좌가 본인 것인지 확인하는 것이 목적이라면 1원 인증 기준으로 연동합니다.
연동 전에 API 키 보관, 환경 분리, 암호화 통신, 인증 코드 정책, 동의 문구, 저장 기준을 정합니다.
1원 송금 요청, 인증 코드 입력, 결과 처리, 실패 시 재시도의 네 단계로 구현합니다.
실패는 유형별로 다르게 처리하고, 응답 지연 시에는 다시 보내기 전에 결과부터 조회합니다.
1원 인증은 성공 흐름보다 실패 흐름을 어떻게 만드느냐에 따라 고객 완료율과 운영 부담이 달라지므로, 실패 처리까지 연동 범위에 포함해 설계하는 것이 좋습니다.
.svg)
.png)
.svg)
.svg)
