BIC / SWIFT 코드 검증 API

소프트웨어에서 BIC 검증 API를 통합하는 방법

1. BIC 검증 API란 무엇입니까?

전신환을 처리하고 IBAN 관련 트랜잭션을 처리할 때, 정확한 SWIFT/BIC 코드를 제공하는 것이 결제를 보증하는 데 필수적입니다.
당사는 S.W.I.F.T SCRL의 공식 BIC 디렉토리에 라이센스를 부여하여 BIC를 자동으로 검증할 수 있는 강력하고 간단한 방법을 제공하고 있습니다. 이 서비스를 통해 내부 용도 소프트웨어에 BIC 코드 디렉토리 조회를 통합할 수 있습니다

BIC 검증 API에는 S.W.I.F.T. SCRL의 사용 권한과 함께 사용되는 SWIFTRef Data Inside. BIC 데이터가 있습니다. 데이터베이스 권한 소유 2019

2. 기능

BIC 검증 API의 주요 기능:

  • BIC를 기반으로 은행에 대한 정보를 검색합니다.
  • 은행 이름과 국가의 일부를 기준으로 BIC 디렉토리를 검색합니다.
  • BIC 디렉토리에서 과거 기록을 검색합니다.
  • 단순하면서 완벽한 API 응답을 사용하여 통합이 용이합니다.


3. API 사용

BIC 검증 API는 REST 기반이며 간단한 HTTP GET 또는 POST 요청을 지원합니다.

수락된 매개 변수는 아래 표에 나열됩니다:

필드명 길이 유형 서술
bic 11 조회할 BIC / SWIFT 코드입니다. 8자 또는 11자로 가능합니다
은행명 256 BIC 디렉토리에서 검색을 수행할 은행 이름의 일부.
국가 2 두 개의 문자 국가 코드. 은행 이름으로 검색할 때 필요합니다.
api_key 128 개인 API 키.
형식 4 반환된 데이터의 형식을 지정하는 데 필요합니다. 현재 지원되는 값: json, xml
제한 정수 선택 사항: 은행 이름으로 검색할 때 결과의 수를 제한하는 데 사용할 수 있습니다.
기록 정수 선택 사항: 은행 및 BIC 검색을 위해 데이터베이스의 이전 기록을 표시하는 데 사용할 수 있습니다.
온라인 포털 내에서 검색 요청을 보호하는 데 사용되는 API 키와 리퀘스트 엔드포인트 URL을 찾을 수 있습니다.


4. API XML 응답 구조

API 응답의 XSD Schema 를 다운로드할 수 있습니다.
반환된 필드에 대한 자세한 설명은 아래 표에서 확인할 수 있습니다:

필드명 타입 길이 항상 있음 설명
수정 플래그 알파벳 1 델타 파일:
• A (추가)
• M (수정)
• D (삭제) 전체 파일 전체 파일:
• A (추가)
변경된 파일 186 번호 기록을 변경하거나 새로운 EVENT의 결과로 변경된 필드(또는 TAG)를 기록합니다.
하나 이상의 열이 이전 기록 인스턴스 또는 이전 EVENT에서 변경된 열을 나타내는 일련 번호로 표시됩니다.
예제 "6,7,8,9"
즉, 이벤트 유형, 이벤트 날짜, BIC8 및 BRANCH BIC가
변경되었습니다.
다음 필드는 '변경되는 필드'에 기록되지 않습니다:
• 기록 키
• 변경된 필드
• 수정된 플래그
기록 키 영숫자 12 파일에 있는 기록의 고유 키
각 기록은 BIC 라이프 주기 내의 이벤트를 나타냅니다.
할당되면 기록 키는 절대 변경되지 않습니다.
이전 기록 키 영숫자 12 아니오 이전에 연결된 이벤트의 기록 키
모든 관련 이벤트는 연관되어 있으며 해당 정보를 사용하여 위치를 지정할 수 있습니다.
다음 기록 키 영숫자 12 아니오 다음과 연결된 이벤트의 기록 키
모든 관련 이벤트가 연관되어 있으며 이 정보를 사용하여 위치를 지정할 수 있습니다
이벤트 유형 영숫자 32 과거, 현재 또는 미래에 발생할 BIC와 관련된 이벤트 또는 변경 설명.
이벤트 유형:
• BIC 발행됨
• BIC 만료됨
• FIN에서 BIC 활성화됨
• FA에서 BIC 활성화됨
• IA에서 BIC 활성화됨
• FIN에서 BIC 비활성화됨
• FA에서 BIC 비활성화됨
• IA에서 BIC 비활성화됨
• BIC 비활성화됨
• BIC 중지됨
• BIC 재활성화됨
• BIC 발행됨
• BIC 상호 변경됨
• BIC 기관명 변경됨
• BIC 주소 변경됨
• FIN 서비스 코드 변경됨
마지막 업데이트 날짜는 BIC 시퀀스의 마지막 줄(즉, 가장 최근의 항목)입니다.
새로운 이벤트가 추가되면 바로 이전 관련 이벤트에서
수정 플래그 및 변경된 필드 열이 업데이트됩니다.
이벤트 날짜 영숫자 8 이벤트 날짜
BIC8 영숫자 8 BIC (기관, 국가 및 관계자 끝자리) 자리:
• 관계자 앞자리 (4 자)
• 국가 코드 (2 자)
• 관계자 끝자리 (2 자)
지점 BIC 영숫자 3 8자 BIC와 연결된 BIC 지점 식별자. 지점 식별자가 없는 경우 XXX가 사용됩니다.
BIC 영숫자 11 전체 BIC: 8자 BIC 및 지점 식별자
기록 상태 영숫자 1 기록의 상태를 나타냅니다:
• [C] = 현재(Current)란 [F]uture(미래) 이벤트를 제외하고 발행일까지 연속적인 최신 이벤트를 나타냅니다
• [H] = 이벤트 연속성의 이전(Historical) 기록
• [F] = 디렉터리의 발행일 이후 발생한 미래 이벤트. 이전에 표시된 현재[C] 이벤트는 미래[F] 이벤트에 지정된 날짜까지 유효합니다.
미래 이벤트의 경우, 날짜는 유효 시작일이 될 시기를 나타냅니다.
운영상 활성화 기록 알파 1 동일한 BIC에 대한 기록이 여러 개 있습니다. 해당 필드는 동일한 BIC에 대한 기록 중 어떤 것이 운영상 활성화 BIC이며 사용해야 하는지를 나타냅니다.
• [Y] 운영상 활성화
• [N] 운영상 비활성화
각 고유의 BIC는 활성화 상태(Y)를 나타내는 단일 기록 항목이 있습니다.
이전[H] 상태가 있는 기록은 항상 [N]으로 표시됩니다.
현재[C]의 기록은 [Y] 또는 [N]를 나타낼 수도 있습니다.
[F]의 기록은 항상 [N]을 나타냅니다.
하위유형 표시 모든 유형 4 엔티티의 비즈니스 유형. 하위유형 표시는 BIC가 있는 기록에 관해서만 제공됩니다.
FIN 전환하기 영숫자 1 엔티티가 FIN에 연결된 상태:
• [Y] FIN에 연결되어 있습니다
• [N] FIN에 연결되지 않았습니다
FA 전환하기 영숫자 1 FileAct를 통한 엔티티 접근성 상태:
• [Y] FileAct에 연결됨
• [N] FileAct에 연결되지 않음
IA 전환하기 알파 1 InterAct를 통한 엔티티 접근성 상태:
• [Y] InterAct에 연결됨
• [N] InterAct에 연결되지 않음
법률상 명칭 전체 105 아니오 기관 상호
기관명 전체 105 기관거래명(공시명)
기관 유형 영숫자 12 주로 금융 중재 및/또는 보조 금융 활동에 종사하는 조직
기관 유형:
• 재정
• 비재무
엔티티 유형 영숫자 16 금융 엔티티의 유형을 식별합니다:
• 법적 실체
• 지점
• 운영상
RE 거리 주소 1 전체 35 아니오 [등록] 거리명
RE 거리 주소 2 전체 35 아니오 [등록] 번지
RE 거리 주소 3 전체 35 아니오 [등록] 건물, 건물명, 층수
RE 거리 주소 4 전체 35 아니오 [등록] 지역
RE 시 전체 35 아니오 [등록] 기관/지점의 도시명
RE CPS 전체 90 아니오 [등록] 소유 기관/지점의 군, 도, 주 또는 기타 행정 구역
RE 우편번호 전체 15 아니오 [등록] 기관/지점의 우편번호
RE 사서함 번호 전체 35 아니오 기관/지점의 사서함 번호와 관련 ZIP 코드가 있는 쉼표로 구분된 필드.
예시
"사서함 103352, 40024"
이를 통해 고객은 전체 사서함 주소를 사용할 수 있습니다:
사서함 103352
40024, 뒤셀도르프 (시)
OP 거리 주소 1 전체 35 아니오 [운영상] 거리 주소
OP 거리 주소 2 전체 35 No [운영상] 번지수
OP 거리 주소 3 전체 35 아니오 [운영상] 건물, 건물명, 층수
OP 거리 주소 4 전체 35 아니오 [운영상] 지역
OP 시 전체 35 아니오 [운영상] 기관/지점의 도시명
OP CPS 전체 90 아니오 [운영상] 소유 기관/지점의 군, 도, 주 또는 기타 행정 구역
OP 우편번호 전체 15 아니오 [운영상] 기관/지점의 우편 번호
OP 사서함 번호 전체 35 아니오 기관/지점의 사서함 번호 및 관련 우편번호가 있는 쉼표로 구분된 필드.
예시
"사서함 103352, 40024"
이를 통해 고객은 전체 사서함 주소를 사용할 수 있습니다:
사서함 103352
40024, 뒤셀도르프 (시)
BR 거리 주소 1 전체 35 아니오 [Branch] 거리명
BR 거리 주소 2 전체 35 아니오 [지점] 번지수
BR 거리 주소 3 전체 35 아니오 [지점] 건물, 건물명, 층
BR 건물 주소 4 전체 35 아니오 [지점] Area
BR 시 전체 35 아니오 [지점] 기관/ 지점의 도시명
BR CPS 전체 90 아니오 [지점] 소유 기관/지점의 군, 도, 주 또는 기타 행정 구역
BR 우편 번호 전체 15 아니오 [지점] 기관/지점의 우편 번호
BR 사서함 번호 전체 35 아니오 기관/지점의 사서함 번호 및 관련 우편 번호가 있는 쉼표로 구분된 필드.
예시
"사서함 103352, 40024"
이를 통해 고객은 전체 사서함 주소를 사용할 수 있습니다:
사서함 103352
40024, 뒤셀도르프 (CITY)
지점 정보 전체 70 아니오 지점 정보
본 문서는 해당 지점이 속한 금융 기관이 제공하는 무료 텍스트 설명입니다. 당분간 해당 정보는 BIC가 있는 항목에서만 제공되며 해당 금융 기관이 해당 추가 정보를 제공하고자 하는 경우에만 제공됩니다. 해당 정보는 BIC 디렉토리에서 공급됩니다.
국가 이름 전체 70 ISO 3166에 표시된 기관/지점의 국가 이름
ISO 국가 코드 영숫자 2 기관/지점 국가의 ISO 3166-1 알파-2 코드
로케이션 코드 전체 유형 1 위치 포함 (형식상 BIC 표준:2009의 포지션 7)
예시:
• 프랑스에서, BIC의 Paris = P입니다
• 벨기에에서, BIC의 브뤼셀 = B입니다
• 미국에서 BIC의 동해안 = 3입니다
FIN 서비스 코드 전체 유형 60 아니오 FIN 서비스 코드(부가 가치 서비스 코드라고도 함)입니다. 서비스 코드는 BIC가 포함된 기록에 대해서만 제공됩니다.
해당 필드는 알파벳 순서로 최대 20개의 3자 코드가 포함될 수 있습니다.
기록 키 BDP 영숫자 12 아니오 첨부파일의 Bank Directory Plus 기록의 고유 키입니다.
필드 A 전체 1 아니오 향후 사용을 위해 예약됨
필드 B 전체 64 아니오 향후 사용을 위해 예약됨
필드 C 전체 128 아니오 향후 사용을 위해 예약됨
필드 D 전체 256 아니오 향후 사용을 위해 예약됨
필드 E 전체 11 아니오 향후 사용을 위해 예약됨
필드 F 전체 12 아니오 향후 사용을 위해 예약됨
API 시스템은 다양한 프로그래밍 언어 및 플랫폼에서 쉽게 분석할 수 있는 XML 형식으로 결과를 반환합니다.

BIC 검색을 위한 API의 예시 XML 응답은 다음과 같습니다:


<result>
<bicdata>
<row>
<modification_flag>A</modification_flag>
<changed_field>34</changed_field>
<record_key>BP0000004OQQ</record_key>
<previous_record_key>BP00000030XZ</previous_record_key>
<next_record_key/>
<event_type>BIC ADDRESS CHANGED</event_type>
<event_date>20150606</event_date>
<bic8>BARCGB22</bic8>
<branch_bic>XXX</branch_bic>
<bic>BARCGB22XXX</bic>
<record_status>C</record_status>
<operationally_active_record>Y</operationally_active_record>
<subtype_indicator>SUPE</subtype_indicator>
<swift_fin>Y</swift_fin>
<swift_fa>N</swift_fa>
<swift_ia>N</swift_ia>
<legal_name>BARCLAYS BANK PLC</legal_name>
<institution_name>BARCLAYS BANK PLC</institution_name>
<institution_type>FINANCIAL</institution_type>
<entity_type>Legal Entity</entity_type>
<re_street_address_1>1, CHURCHILL PLACE</re_street_address_1>
<re_street_address_2/>
<re_street_address_3/>
<re_street_address_4/>
<re_city>LONDON</re_city>
<re_cps/>
<re_zip_code>E14 5HP</re_zip_code>
<re_pob_number/>
<op_street_address_1>1 CHURCHILL PLACE</op_street_address_1>
<op_street_address_2/>
<op_street_address_3/>
<op_street_address_4/>
<op_city>LONDON</op_city>
<op_cps>LONDON E14 5HP</op_cps>
<op_zip_code/>
<op_pob_number/>
<br_street_address_1/>
<br_street_address_2/>
<br_street_address_3/>
<br_street_address_4/>
<br_city/>
<br_cps/>
<br_zip_code/>
<br_pob_number/>
<branch_information>(ALL U.K. OFFICES)</branch_information>
<country_name>UNITED KINGDOM</country_name>
<iso_country_code>GB</iso_country_code>
<location_code>2</location_code>
<fin_service_codes>EBAERPFINSCOSTGTGT</fin_service_codes>
<record_key_bdp>BD00000006FO</record_key_bdp>
<field_a/>
<field_b/>
<field_c/>
<field_d/>
<field_e/>
<field_f></field_f>
</row>
</bicdata>
<errors/>
</result>




5. API 오류

오류가 발생하면 API는 오류 메시지가 포함된 XML 응답을 반환합니다.

해당 XML 태그는 XML 응답의 다른 필드 없이 반환됩니다.

아래에는 반환될 수 있는 모든 가능한 오류 메시지에 대한 설명이 나와 있습니다:

상태 코드 유형 설명
301 계정 오류 API 키가 잘못되었습니다
302 계정 오류 구독이 만료됨
303 계정 오류 사용 가능한 쿼리 없음
304 계정 오류 해당 API에 액세스할 수 없습니다
401 입력 오류 SWIFT 길이 8자 또는 11자로 허용됨'
402 입력 오류 Bank Name Invalid! Bank search should be minimum of 4 characters.
허용된 문자 a-z, A-Z, 0-9, [space]!
403 입력 오류 국가 코드가 잘못되었습니다! 국가 코드는 2자로 허용됩니다. 예: UK, DE, FR