법인 예금주명이 잘려 돌아올 때: 계좌 실명조회 비교 로직 설계
법인 판매자의 계좌를 조회했는데 상호의 끝부분이 빠져 돌아오면 어떻게 처리해야 할까요? 단순히 저장된 회사명과 글자가 다르다는 이유로 계좌 변경을 거절하면 정상 고객에게 같은 자료를 여러 번 요구할 수 있습니다. 반대로 앞부분이 같다는 이유로 자동 승인하면 필요한 확인을 건너뛸 수 있습니다.
이번 글은 APICK 계좌 예금주 실명 조회 결과를 비교하는 로직에 집중합니다. 일반적인 정산 계좌 변경 흐름과 달리, 원천 금융기관의 문자열 길이 제한을 어떻게 표시하고 사람이 확인할 상황을 어떻게 분류할지가 핵심입니다. API의 명의 조회 결과를 추가 확인이 필요한 신호로 다루는 방법을 살펴보겠습니다.
공식 문서가 설명하는 이름 잘림의 범위
APICK 문서는 계좌실명을 금융기관이 반환한 그대로 전달한다고 안내합니다. 일부 은행은 예금주명을 10자까지만 제공해 더 긴 이름의 뒷부분이 잘릴 수 있습니다. 다른 은행은 10자를 넘는 이름도 반환하므로 모든 응답을 10자로 자르는 것은 맞지 않습니다. 전체 명의를 다시 받는 별도 파라미터도 안내돼 있지 않습니다. 계좌실명 길이 제한 설명을 비교 정책의 전제로 확인하세요.
응답이 10자라는 사실만으로 잘렸다고 확정할 수도 없습니다. 실제 이름 자체가 10자일 수 있고, 비교 기준으로 가져온 회사명과 계좌 개설 명의의 표기가 다를 수도 있습니다. 사업자 정보의 회사명이나 서비스 화면의 브랜드 이름을 곧바로 은행 명의의 정답으로 사용하지 마세요. 어떤 자료를 기준 명의로 사용할지는 계좌 관계를 확인하는 업무 절차에서 먼저 정해야 합니다.
비교 원본과 표시값을 분리하기
- 기준 명의: 서비스가 정한 확인 절차에서 확보한 값과 그 출처를 관리합니다.
- 은행 반환 명의: APICK에서 받은 원문을 허용된 보관 범위에서 구분해 다룹니다.
- 비교 결과: 동일 문구인지, 표시 차이인지, 잘림 가능성이 있는지, 추가 자료가 필요한지 이유를 남깁니다.
사용자에게 보여주는 줄임말이나 화면용 문자열로 원본을 덮어쓰지 않는 것이 좋습니다. 원문이 달라졌는지 확인하기 어려워지고 재현도 힘들어집니다. 조회 정보의 원문을 무조건 장기간 저장하라는 뜻은 아닙니다. 저장 목적과 접근 권한, 보관 기한을 먼저 정하고 검토 기록에는 가능하면 원문 대신 판단 사유와 요청 ID를 남깁니다.
1. 원천 응답을 확인하는 최소 요청
API 경로는 POST /rest/account_realname이며 account_num과 은행 식별값을 보냅니다. 다음 예제는 권한이 확인된 서버 테스트용 환경변수만 사용합니다. 응답 파일은 개인·계좌 정보를 담을 수 있으므로 저장소에 커밋하거나 협업 메신저에 그대로 첨부하지 마세요.
umask 077
curl --fail-with-body --request POST 'https://apick.app/rest/account_realname' \
--header "Authorization: Bearer ${APICK_API_KEY:?Set a server-side key}" \
--form-string "bank_code=${APICK_TEST_BANK_CODE:?Set an approved bank code}" \
--form-string "account_num=${APICK_TEST_ACCOUNT:?Set an authorized test account}" \
--connect-timeout 10 --max-time 60 \
--output holder-response.private.json주요 필드는 data.계좌실명, data.success, api.success입니다. 명의 비교는 HTTP 상태 확인, JSON 해석, 서버·조회 성공 확인이 끝난 뒤에 진행합니다. 통신 장애나 빈 응답을 “다른 명의”로 분류하지 않아야 합니다. data.error가 들어오는 경우에도 사용자 화면이나 로그에 전체 응답을 그대로 출력하기보다 안전한 운영 오류 경로로 처리하세요.
2. 이름 비교는 보수적인 다중 상태로 만들기
다음 Node.js 함수는 우리 애플리케이션의 비교 로직 예시입니다. APICK이 제공하는 자동 매칭 기능이나 승인 결과가 아닙니다. NFC 정규화와 앞뒤 공백 정리만 기본 처리하고, 공백 차이는 별도 검토 대상으로 표시합니다. 주식회사 표기, 괄호, 영문, 특수문자를 임의로 삭제해 같은 사람이나 회사로 합치는 규칙은 넣지 않았습니다.
export function compareHolderName(expectedName, returnedName) {
if (typeof expectedName !== "string" || typeof returnedName !== "string")
return { decision: "needs_review", reason: "missing_name" };
const expected = expectedName.normalize("NFC").trim();
const returned = returnedName.normalize("NFC").trim();
if (!expected || !returned)
return { decision: "needs_review", reason: "missing_name" };
if (expected === returned)
return { decision: "same_text", reason: "exact_text_match" };
// A spacing-only match is a review hint, never an approval.
const withoutSpaces = value => value.replace(/\s+/gu, "");
if (withoutSpaces(expected) === withoutSpaces(returned))
return { decision: "needs_review", reason: "spacing_difference" };
const expectedChars = Array.from(expected);
const returnedChars = Array.from(returned);
// 10 characters is a documented limit for some banks, not every bank.
const mayBeTruncated = returnedChars.length === 10
&& expectedChars.length > returnedChars.length
&& expectedChars.slice(0, returnedChars.length).join("") === returned;
if (mayBeTruncated)
return { decision: "needs_review", reason: "possible_source_truncation" };
return { decision: "needs_review", reason: "different_text" };
}same_text는 비교한 두 문자열이 같다는 뜻일 뿐입니다. 계좌에 접근 가능한 사람인지, 판매자와 계좌의 관계가 승인 기준을 충족하는지까지 판단하지 않습니다. possible_source_truncation 역시 잘림 가능성을 표시하는 내부 이유값이며, 원천 은행이 실제로 잘랐다는 확정 결과가 아닙니다. 다른 문구가 반환된 경우에도 원인을 확인할 때까지 계좌 소유자를 단정하지 않습니다.
3. 비교 결과를 검토 화면에 연결하기
검토 화면에는 조회 시각과 은행, 마스킹된 계좌, 비교 결과의 이유를 보여줍니다. 이름 원문을 볼 수 있는 담당자는 필요한 역할로 제한하세요. 잘림 가능성이 있는 경우에는 짧아진 문자열을 추측으로 복원하거나 이름 뒤를 임의로 붙이지 않고, 허용된 금융기관 확인 경로나 추가 자료 검토로 넘어가도록 설계합니다. 같은 이유로 실패한 요청을 반복 호출해도 금융기관의 반환 한계를 해결할 수 있다고 보장할 수 없습니다.
문자열 비교 규칙을 바꾸면 기존 요청의 판정도 달라질 수 있습니다. 비교 규칙 버전과 판정 시각을 남기고, 변경된 규칙을 적용하기 전에 과거의 비식별 테스트 사례로 확인하는 편이 좋습니다. 고객 식별값과 원문 명의 전체를 테스트 저장소에 넣는 대신, 개인정보를 포함하지 않는 합성 문자열로 분기와 길이 처리를 점검할 수 있습니다.
테스트할 경계값 여섯 가지
- 기준 명의 또는 은행 반환 명의가 비어 있으면 확인 필요로 남기는지
- 두 문자열이 같을 때 문자열 일치라는 의미만 반환하는지
- 공백만 다른 경우 별도 사유로 표시되는지
- 긴 기준값의 앞 10자가 반환되면 잘림 가능성으로 분류하는지
- 반환값이 10자여도 접두 부분이 다르면 잘림으로 확정하지 않는지
- 10자를 넘는 정상 응답을 잘라 버리지 않고 그대로 비교하는지
한글은 JavaScript 문자열 길이 계산 방식과 정규화 상태도 확인하는 편이 좋습니다. 예제는 Array.from으로 유니코드 코드 포인트 단위 배열을 만들어 비교합니다. 이것이 모든 금융기관의 문자 길이 계산 규칙을 재현한다고 보장하지는 않습니다. 조합 문자·특수문자가 포함된 값은 실제 허용된 테스트와 공급자 안내를 바탕으로 검토 정책을 정하세요.
호출 비용을 줄이는 방법은 비교 단계의 분리
2026-10-11 공식 공개 단가는 건당 60P입니다. 과금되는 조회 500건이면 30,000P로 계산할 수 있습니다. 이미 받은 응답을 애플리케이션에서 비교하는 함수 자체는 APICK을 다시 호출하지 않습니다. 원본 조회를 반복하는 단계와 비교 규칙만 다시 적용하는 단계를 구분하면 불필요한 재호출을 찾아낼 수 있습니다. 보관과 재사용은 허용된 목적·기간 안에서만 설계하세요.
예금주 조회는 공통 시작 가이드의 최초 1회 이상 결제 필요 목록에 포함됩니다. 과금되는 재조회는 예산에 추가해야 하며, 이름이 잘렸다고 해서 그 호출이 무료라고 가정하면 안 됩니다. 실제 사용 내역은 api.cost와 api.pl_id로 대조하세요. 포인트를 원화로 임의 환산하지 않았고 세금·개별 계약 조건도 확인하지 않았습니다.
자주 묻는 질문
10자 이름이 오면 무조건 잘린 건가요?
아닙니다. 이름 자체가 10자일 수도 있습니다. 이 글의 로직은 가능성을 표시해 담당자 확인으로 넘깁니다.
전체 명의를 받는 옵션이 있나요?
확인한 공식 가이드에는 별도 파라미터가 없다고 명시돼 있습니다. 필요한 경우 해당 금융기관 확인 경로와 공급자 안내를 검토하세요.
“주식회사”나 괄호를 지우면 일치율이 높아지지 않나요?
표기 차이를 줄일 수 있어도 서로 다른 명의를 같은 값으로 합칠 위험이 있습니다. 근거가 없는 자동 삭제 규칙보다 원문 보존과 확인 필요 분류를 우선 검토하세요.
APICK으로 연동 범위와 운영 조건 확인하기
계좌 예금주 실명 조회 개발가이드에서 입력과 응답을 확인한 뒤, 실제로 허용된 테스트 대상과 기준 명의로 연동을 검토해 보세요. 은행코드 조회와 함께 구성하면 은행 선택값을 문자열 코드로 관리할 수 있습니다. 구체적인 조회 목적과 개인정보 처리 조건은 공급자 안내 및 서비스의 처리 근거와 맞춰야 합니다.
문서·가격 확인: 2026-10-11 UTC. 공식 요금표 · 인증·이용 시작 안내. 공개 문서를 기준으로 작성했으며 실제 API 호출이나 금융 거래는 실행하지 않았습니다. 코드는 설명용 서버 예제입니다. 인증키와 계좌·명의 정보는 자리표시자로만 다룹니다.
댓글
댓글 쓰기