예금주 조회

무엇을 조회하나요

은행코드와 계좌번호를 보내면 예금주명을 돌려줍니다. 송금하기 전에 거래처 계좌가 맞는지 확인할 때 쓰세요.

경로	용도
`POST /v1/bankAccountHolders:inquire`	계좌 한 건의 예금주 조회
`POST /v1/bankAccountHolders:bulkInquire`	계좌 최대 100건의 예금주 조회

이용 조건

두 경로 모두 발급자 등록, 공동인증서, 요청자 관리번호(Bolta-Client-Reference-Id)가 필요 없고 구독 플랜 제한도 없습니다. Authorization 헤더에 Basic {apiKey}만 넣으면 됩니다. 자세한 내용은 인증 가이드를 참고하세요.

요금

예금주를 돌려준 계좌마다 50포인트를 차감합니다. 예금주를 찾지 못했거나 조회에 실패한 계좌, 입력 오류, 한도 초과, 잔액 부족, 테스트 키 호출은 차감하지 않습니다. 일반 계좌는 한 요청 안에서 같은 은행코드와 계좌번호를 여러 번 넣어도 한 번만 차감합니다. 금액 확인형 가상계좌는 고유한 amount마다 차감합니다. 요청을 다시 보내면 다시 차감합니다.

단건 조회

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와 아래 응답을 반환합니다.

{
  "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개 이하로 넣으세요.

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" }
    ]
  }'

계좌마다 결과 하나를 요청과 같은 순서로 돌려줍니다.

{
  "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 통신 오류

전체 에러 코드는 에러 코드를 참고하세요.

API 소개

API 가이드

사용 사례

SDK/노코드 연동

무엇을 조회하나요

이용 조건

요금

단건 조회

지원 은행

일괄 조회

금액 확인형 가상계좌

하루 한도

테스트 키

오류

관련 문서

​무엇을 조회하나요

​이용 조건

​요금

​단건 조회

​지원 은행

​일괄 조회

​금액 확인형 가상계좌

​하루 한도

​테스트 키

​오류

​관련 문서

무엇을 조회하나요

이용 조건

요금

단건 조회

지원 은행

일괄 조회

금액 확인형 가상계좌

하루 한도

테스트 키

오류

관련 문서