> ## Documentation Index > Fetch the complete documentation index at: https://docs.bolta.io/llms.txt > Use this file to discover all available pages before exploring further. # 예금주 조회 > 은행코드와 계좌번호로 예금주명을 조회하는 API의 이용 조건, 요금, 일괄 조회와 금액 확인형 가상계좌 처리 방법을 안내합니다. ## 무엇을 조회하나요 은행코드와 계좌번호를 보내면 예금주명을 돌려줍니다. 송금하기 전에 거래처 계좌가 맞는지 확인할 때 쓰세요. | 경로 | 용도 | | ----------------------------------------- | ------------------ | | `POST /v1/bankAccountHolders:inquire` | 계좌 한 건의 예금주 조회 | | `POST /v1/bankAccountHolders:bulkInquire` | 계좌 최대 100건의 예금주 조회 | ## 이용 조건 두 경로 모두 발급자 등록, 공동인증서, 요청자 관리번호(`Bolta-Client-Reference-Id`)가 필요 없고 구독 플랜 제한도 없습니다. `Authorization` 헤더에 `Basic {apiKey}`만 넣으면 됩니다. 자세한 내용은 [인증 가이드](/docs/api-introduction/authentication)를 참고하세요. ## 요금 예금주를 돌려준 계좌마다 **50포인트**를 차감합니다. 예금주를 찾지 못했거나 조회에 실패한 계좌, 입력 오류, 한도 초과, 잔액 부족, 테스트 키 호출은 차감하지 않습니다. 일반 계좌는 한 요청 안에서 같은 은행코드와 계좌번호를 여러 번 넣어도 한 번만 차감합니다. 금액 확인형 가상계좌는 고유한 `amount`마다 차감합니다. 요청을 다시 보내면 다시 차감합니다. ## 단건 조회 ```bash theme={"dark"} curl -X POST https://xapi.bolta.io/v1/bankAccountHolders:inquire \ -H "Authorization: Basic {apiKey}" \ -H "Content-Type: application/json" \ -d '{ "bankCode": "088", "accountNumber": "100-0000-001" }' ``` | 필드 | 형식 | 필수 | 설명 | | --------------- | ------- | --- | --------------------------------------- | | `bankCode` | string | 예 | 금융결제원 3자리 은행코드. 아래 지원 은행 표 참고 | | `accountNumber` | string | 예 | 계좌번호. 하이픈을 포함해도 됩니다. 하이픈을 뺀 숫자가 6\~20자리 | | `amount` | integer | 아니오 | 금액 확인형 가상계좌의 입금 금액(원). 일반 계좌는 비워 두세요 | API는 `200 OK`와 아래 응답을 반환합니다. ```json theme={"dark"} { "bankCode": "088", "accountNumber": "1000000001", "holderName": "홍길동" } ``` | 필드 | 형식 | 설명 | | --------------- | ------ | ----------- | | `bankCode` | string | 요청한 은행코드 | | `accountNumber` | string | 하이픈을 뗀 계좌번호 | | `holderName` | string | 예금주명 | ## 지원 은행 `bankCode`는 금융결제원 3자리 표준 은행코드입니다. 국내 은행은 아래 26곳을 지원합니다. | `bankCode` | 은행 | | ---------- | ---------- | | `002` | 산업은행 | | `003` | 기업은행 | | `004` | 국민은행 | | `005` | 외환은행 | | `007` | 수협 | | `011` | 농협중앙회 | | `012` | 지역농협 | | `020` | 우리은행 | | `023` | SC제일은행 | | `027` | 씨티은행 | | `031` | iM뱅크(대구은행) | | `032` | 부산은행 | | `034` | 광주은행 | | `035` | 제주은행 | | `037` | 전북은행 | | `039` | 경남은행 | | `045` | 새마을금고 | | `048` | 신협 | | `050` | 저축은행 | | `064` | 산림조합 | | `071` | 우체국 | | `081` | 하나은행 | | `088` | 신한은행 | | `089` | 케이뱅크 | | `090` | 카카오뱅크 | | `092` | 토스뱅크 | 외국계 은행은 `054` HSBC은행, `055` 도이치은행, `056` 알비에스피엘씨은행, `057` 제이피모간체이스은행, `058` 미즈호코퍼레이트은행, `059` 미쓰비시도쿄UFJ은행, `060` BOA, `061` 비엔피파리바은행, `062` 중국공상은행, `063` 중국은행, `067` 중국건설은행을 지원합니다. 목록에 없는 코드로 조회하면 `400`과 `UNSUPPORTED_BANK`를 반환합니다. `001` 한국은행, `008` 수출입은행, `026` 서울은행, `052` 모건스탠리은행, `065` 대화은행, `066` 교통은행, `900` HANMI BANK, `901` KANSAI MIRAI BANK, `902` KEB 하나은행(JP)이 여기에 해당합니다. ## 일괄 조회 `accounts`에 계좌를 1개 이상 100개 이하로 넣으세요. ```bash theme={"dark"} curl -X POST https://xapi.bolta.io/v1/bankAccountHolders:bulkInquire \ -H "Authorization: Basic {apiKey}" \ -H "Content-Type: application/json" \ -d '{ "accounts": [ { "bankCode": "088", "accountNumber": "1000000001" }, { "bankCode": "089", "accountNumber": "1000000004" } ] }' ``` 계좌마다 결과 하나를 요청과 같은 순서로 돌려줍니다. ```json theme={"dark"} { "results": [ { "bankCode": "088", "accountNumber": "1000000001", "holderName": "홍길동", "error": null }, { "bankCode": "089", "accountNumber": "1000000004", "holderName": null, "error": { "code": "AMOUNT_REQUIRED", "message": "입금 금액이 정해진 가상계좌입니다. 총 지급 금액을 입력한 뒤 예금주를 다시 조회해 주세요." } } ] } ``` | 필드 | 형식 | 설명 | | ---------------------- | -------------- | ----------------------------------- | | `results` | array | 요청한 계좌마다 항목 하나. 순서는 요청과 같습니다 | | `results[].holderName` | string 또는 null | 예금주명. 찾지 못했으면 `null` | | `results[].error` | object 또는 null | 찾지 못한 원인. `code`는 단건 조회 오류 코드와 같습니다 | 항목 하나라도 형식이 틀리면 요청 전체를 `400 INVALID_REQUEST`로 거절합니다. `error.code`가 `BANK_UNAVAILABLE`인 항목은 판정하지 못한 계좌입니다. 잠시 후 그 계좌만 다시 조회하세요. 한 계좌도 판정하지 못하면 이 응답 대신 `503 BANK_UNAVAILABLE`을 반환합니다. ## 금액 확인형 가상계좌 입금 금액이 정해진 가상계좌는 금액을 함께 보내야 예금주를 확인합니다. `amount` 없이 조회하면 `AMOUNT_REQUIRED`를 반환합니다. 그 계좌로 보낼 총 지급 금액을 `amount`에 넣어 다시 조회하세요. 금액이 다르면 `AMOUNT_MISMATCH`를 반환합니다. ## 하루 한도 하루에 조회할 수 있는 계좌는 **10,000개**입니다. 요청 수가 아니라 조회한 계좌 수로 셉니다. 테스트 키와 라이브 키는 한도를 따로 셉니다. 한도에 도달하면 `429`와 `RATE_LIMITED`를 반환합니다. `Retry-After` 뒤에 다시 시도하세요. 조회 한 건은 최대 45초까지 기다립니다. 넘으면 `503 BANK_UNAVAILABLE`로 끝나고 차감하지 않습니다. ## 테스트 키 테스트 키는 포인트를 차감하지 않고 아래 계좌번호만 받습니다. 은행코드는 지원 은행이면 무엇이든 됩니다. | 계좌번호 | 결과 | | ------------ | ---------------------------------------------------------------------------- | | `1000000001` | `holderName`이 `홍길동` | | `1000000002` | `holderName`이 `(주)볼타` | | `1000000003` | `ACCOUNT_NOT_VERIFIED` | | `1000000004` | `amount`가 없으면 `AMOUNT_REQUIRED`, `20000`이면 `김볼타`, 그 외 금액이면 `AMOUNT_MISMATCH` | | `1000000005` | `BANK_UNAVAILABLE` | 목록 밖 계좌번호는 `400 INVALID_REQUEST`를 반환합니다. ## 오류 예금주를 찾지 못하면 단건 조회는 HTTP 400으로 응답하고, 일괄 조회는 HTTP 200 응답의 `results[].error`에 오류를 담습니다. | 상태 코드 | 에러 코드 | 발생 조건 | | ----- | -------------------------------------- | ------------------------------------------------- | | `400` | `INVALID_REQUEST` | 요청 형식 오류, 계좌 100개 초과, 테스트 키로 안내 목록 밖 계좌 조회 | | `400` | `ACCOUNT_NOT_VERIFIED` | 계좌를 확인하지 못함. 은행코드와 계좌번호를 확인하세요 | | `400` | `ACCOUNT_NOT_AVAILABLE` | 입금이 정지된 가상계좌. 계좌를 발급한 기관에 문의하세요 | | `400` | `AMOUNT_REQUIRED` | 입금 금액이 정해진 가상계좌. `amount`를 넣어 다시 조회하세요 | | `400` | `AMOUNT_MISMATCH` | 입력한 `amount`가 가상계좌에 정해진 금액과 다름 | | `400` | `AMOUNT_VERIFICATION_UNAVAILABLE` | 금액 확인형 가상계좌를 지금은 조회할 수 없음. 계좌를 발급한 곳에서 예금주를 확인하세요 | | `400` | `UNSUPPORTED_BANK` | 예금주 조회를 지원하지 않는 은행코드 | | `401` | - | API 키 인증 실패. 응답 본문 없음 | | `402` | `PAYMENT_REQUIRED` | 포인트 잔액 부족. 개발자센터에서 충전하세요 | | `403` | `FORBIDDEN` | 접근 권한 없음 | | `409` | `POINT_RESERVED_BY_IN_FLIGHT_REQUESTS` | 처리 중인 요청까지 합치면 잔액 부족. 충전하거나 끝난 뒤 다시 요청하세요 | | `429` | `RATE_LIMITED` | 하루 조회 한도 초과. `Retry-After` 뒤에 다시 시도하세요 | | `500` | `INTERNAL_SERVER_ERROR` | 서버 내부 오류 | | `503` | `BANK_UNAVAILABLE` | 은행 점검이나 연결 오류 | | `503` | `LOOKUP_UNAVAILABLE` | 조회 보호 한도를 판정할 수 없음 | | `503` | `SERVICE_UNAVAILABLE` | 일시적인 내부 API 통신 오류 | 전체 에러 코드는 [에러 코드](/docs/api-introduction/error-codes)를 참고하세요. ## 관련 문서 * [예금주 단건 조회 API](/api-reference/예금주-조회/예금주-단건-조회) * [예금주 일괄 조회 API](/api-reference/예금주-조회/예금주-일괄-조회) * [요금 안내](/docs/api-introduction/pricing) * [입출금내역 조회](/docs/api-introduction/bank-account-transactions)