API-интерфейс для проверки BIC и SWIFT

Как интегрировать API-интерфейс для проверки BIC в ваше программное обеспечение

1. Что такое API-интерфейс для проверки BIC?

При обработке безналичных платежей и проведении транзакций, в которых используется IBAN, использование правильного BIC или SWIFT кода является залогом успешной оплаты.
Наша компания имеет доступ к официальному каталогу BIC кодов от S.W.I.F.T SCRL, что позволяет использовать простой и удобный способ автоматической проверки BIC. Наше решение позволяет интегрировать систему проверки BIC-кода прямо в ваше программное обеспечение, и использовать его для решения внутренних проблем и вопросов

API-интерфейс для проверки BIC предоставляет доступ к SWIFTRef данным. Вся информация о BIC используется с согласия S.W.I.F.T. SCRL. Все права на базу данных кодов принадлежат нашей компании 2018

2. Основные функции

Ключевые функции API-интерфейса для проверки BIC:

  • Получение информации о банке на основе BIC.
  • Поиск по каталогу кодов с использованием наименования банка и страны.
  • Поиск по каталогу кодов и ранее сделанным записям.
  • Использование базового и расширенного API-интерфейса для простой и быстрой интеграции.


3. Использование API

API-интерфейс для проверки BIC основан на технологии REST, и поддерживает простые запросы HTTP GET и POST.

Допустимые параметры представлены в таблице ниже:

Наименование поля Длина Тип Описание
bic 11 Строка Поиск по коду BIC или SWIFT. Включает в себя 8 или 11 символов.
bank_name 256 Строка Часть наименования банка для поиска в каталоге кодов.
country 2 Строка Код страны из двух букв. Требуется при поиске информации по наименованию банка.
api_key 128 Строка Ваш личный API-ключ.
format 4 Строка Используется для определения формата получаемых данных. В настоящее время поддерживаются следующие значения: json, xml
limit Целое число Опционально: может использоваться для ограничения количества результатов при поиске по наименованию банка.
hist Целое число Опционально: может использоваться для отображения ранее созданных записей при поиске по коду или наименованию банка.
Используя онлайн-портал, вы сможете получить ваш API-ключ, а также конечную ссылку для отправления запросов, которые используются для формирования поисковых запросов.


4. Структура ответа API XML

Вы всегда можете скачать XSD схему ответа API.
Кроме того, подробное описание возможных ответов представлено в таблице ниже:

Наименование поля Тип Длина Всегда присутствует Описание
MODIFICATION FLAG Только буквы 1 Да В дельта-файлах:
• A (добавление)
• M (изменение)
• D (удаление):
• A (добавление)
CHANGED FIELD Только числа 186 Нет Сохраняет информацию о поле или теге, которые были изменены как в результате запроса на внесение изменений, так и в результате нового события EVENT.
Одна или несколько колонок, представляющие собой комбинацию цифр, при этом, каждое число отображает изменения, который произошли после нового события EVENT.
Пример "6,7,8,9"
Получается, что EVENT TYPE, EVENT DATE, BIC8, и BRANCH BIC были
изменены.
Следующие поля не указываются при отображении поля CHANGED FIELD:
• RECORD KEY
• CHANGED FIELD
• MODIFICATION FLAG
RECORD KEY Только числа и буквы 12 Да Уникальный ключ выбранной записи
Каждая запись представляет собой отдельное событие в цикле существования BIC.
Поле RECORD KEY никогда не изменяется после первичного назначения.
PREVIOUS RECORD KEY Только числа и буквы 12 Нет Поле RECORD KEY предыдущего связанного события EVENT
Все события связаны между собой, и могут быть обнаружены благодаря использованию данной информации.
NEXT RECORD KEY Только числа и буквы 12 Нет Поле RECORD KEY следующего связанного события EVENT
Все события связаны между собой, и могут быть обнаружены благодаря использованию данной информации.
EVENT TYPE Только буквы 32 Да Событие EVENT, или изменение описания BIC, которое произошло, происходит или произойдет в будущем.
Типы событий:
• BIC ISSUED
• BIC EXPIRED
• BIC ACTIVATED ON FIN
• BIC ACTIVATED ON FA
• BIC ACTIVATED ON IA
• BIC DEACTIVATED ON FIN
• BIC DEACTIVATED ON FA
• BIC DEACTIVATED ON IA
• BIC DEACTIVATED
• BIC SUSPENDED
• BIC REACTIVATED
• BIC PUBLISHED
• BIC LEGAL NAME CHANGED
• BIC INSTITUTION NAME CHANGED
• BIC ADDRESS CHANGED
• FIN SERVICE CODE CHANGED
Дата последнего обновления представляет собой дату последней записи в BIC.
При добавлении нового события EVENT, поля MODIFICATION FLAG и CHANGED
FIELD будут обновлены с удалением информации о последнем произошедшем событии EVENT.
EVENT DATE Только числа и буквы 8 Да Дата события EVENT
BIC8 Только числа и буквы 8 Да BIC (учреждение, страна и участник), где:
• Префикс (4 симв.)
• Код страны (2 симв.)
• Суффикс (2 симв.)
BRANCH BIC Только числа и буквы 3 Да Идентификатор отделения BIC, связанный с 8-значным кодом BIC. При отсутствии отделения используется XXX.
BIC Только числа и буквы 11 Да Полный BIC: 8-значный идентификатор отделения BIC
RECORD STATUS Только буквы 1 Да Указывает текущее состояние записи:
• [C] = текущая запись, которая используется для отображение последнего события на момент публикации, за исключением будущих событий (F).
• [H] = исторические записи для выбранного кода.
• [F] = будущие события, которые произойдут после публикации данных. Текущее событие (С) будет действовать до момента, определенного в одном из будущих (F) событий.
Для будущий событий FUTURE, дата начала действия указывается в поле VALID FROM.
OPERATIONALLY ACTIVE RECORD Альфа 1 Да Существует большое количество записей для одного BIC. Данное поле указывает, какая из имеющихся записей о BIC является активной, и должна использования для ведения операционной деятельности.
• [Y] Активно
• [N] Неактивно
Для каждого кода BIC существует всего одна активная запись, имеющая статус ACTIVE (Y).
Исторические записи [H] всегда обозначены символом [N].
Текущие записи могут иметь статус [Y] или [N].
Будущие записи [F] всегда обозначены символом[N].
SUBTYPE INDICATOR Любое 4 Да Юридическая форма компании. Поле Subtype Indicator используется только для записей, имеющих BIC.
SWIFT FIN Только буквы 1 Да Наличие или отсутствия подключения к FIN:
• [Y] - подключено к FIN
• [N] - не подключено к FIN
SWIFT FA Только буквы 1 Да Доступность юридического лица через FileAct:
• [Y] - подключено к FileAct
• [N] - не подключено к FileAct
SWIFT IA Только буквы 1 Да Доступность юридического лица через InterAct:
• [Y] - подключено к InterAct
• [N] - не подключено к InterAct
LEGAL NAME Любое 105 Нет Официальное наименование юридического лица
INSTITUTION NAME Любое 105 Да Торговое наименование юридического лица (опубликовано)
INSTITUTION TYPE Только буквы 12 Да Компания, выполняющая роль посредника в предоставлении финансовых услуг
Тип организации:
• FINANCIAL
• NONFINANCIAL
ENTITY TYPE Только буквы 16 Да Определяет организационно-правовую форму компании:
• Юридическое лицо
• Отделение
• Операционная касса
RE STREET ADDRESS 1 Любое 35 Нет Адрес регистрации
RE STREET ADDRESS 2 Любое 35 Нет Адрес регистрации
RE STREET ADDRESS 3 Любое 35 Нет Номер дома, строения и офиса
RE STREET ADDRESS 4 Любое 35 Нет Район регистрации
RE CITY Любое 35 Нет Город регистрации отделения или юридического лица
RE CPS Любое 90 Нет Страна, штат или регион регистрации юридического лица или отделения
RE ZIP CODE Любое 15 Нет Индекс регистрации юридического лица или отделения
RE POB NUMBER Любое 35 Нет Разделенные запятыми значения POB отделения или юридического лица, а также индекс.
Например,
"POB 103352, 40024"
Клиенты получают возможность использования полного адреса:
POB 103352
40024, DUESSELDORF (CITY)
OP STREET ADDRESS 1 Любое 35 Нет Улица, на которой ведется операционная деятельность
OP STREET ADDRESS 2 Любое 35 Нет Улица, на которой ведется операционная деятельность
OP STREET ADDRESS 3 Любое 35 Нет Номер дома, строения и офиса, в котором ведется операционная деятельность
OP STREET ADDRESS 4 Любое 35 Нет Район, в котором ведется операционная деятельность
OP CITY Любое 35 Нет Город, в котором ведется операционная деятельность
OP CPS Любое 90 Нет Страна штат или регион, в котором ведется операционная деятельность
OP ZIP CODE Любое 15 Нет Индекс, на территории действия которого ведется операционная деятельность
OP POB NUMBER Любое 35 Нет Разделенные запятыми значения POB отделения или юридического лица, а также индекс.
Например,
"POB 103352, 40024"
Клиенты получают возможность использования полного адреса:
POB 103352
40024, DUESSELDORF (CITY)
BR STREET ADDRESS 1 Любое 35 Нет Улица, на которой ведется деятельность отделения
BR STREET ADDRESS 2 Любое 35 Нет Улица, на которой ведется деятельность отделения
BR STREET ADDRESS 3 Любое 35 Нет Номер дома, строения и офиса, в котором ведется деятельность отделения
BR STREET ADDRESS 4 Любое 35 Нет Район, в котором ведется деятельность отделения
BR CITY Любое 35 Нет Город, в котором ведется деятельность отделения
BR CPS Любое 90 Нет Страна, штат или регион, в котором ведется деятельность отделения
BR ZIP CODE Любое 15 Нет Индекс, на территории действия которого ведется деятельность отделения
BR POB NUMBER Любое 35 Нет Разделенные запятыми значения POB отделения или юридического лица, а также индекс.
Например,
"POB 103352, 40024"
Клиенты получают возможность использования полного адреса:
POB 103352
40024, DUESSELDORF (CITY)
BRANCH INFORMATION Любое 70 Нет Информация об отделении
Текстовое описание отделения, предоставленное финансовой организацией, к которой оно относится. В настоящее время данная информация доступна только для записей с BIC, а также только в том случае, если компания хочет предоставить такую информацию. Информация загружается из каталога BIC.
COUNTRY NAME Любое 70 Да Название страны, на территории которой работает юридическое лицо, в соответствии со стандартом ISO 3166
ISO COUNTRY CODE Только буквы 2 Да Двухзначный код страны в соответствии с ISO 3166-1
LOCATION CODE Любое 1 Да Указывает на расположение (обычно находится на 7 позиции стандарта BIC 2009)
Например:
• Для FR, BIC в Париже = P
• Для BE, BIC в Брюсселе = B
• Для US, BIC на Восточном Побережье = 3
FIN SERVICE CODES Любое 60 Нет Служебные коды FIN (коды для обозначения дополнительных услуг). Такие коды указываются только для записей с BIC.
Данное поле может содержать до двадцати кратких буквенных обозначений.
RECORD KEY BDP Только числа и буквы 12 Нет Уникальный код записи Bank Directory Plus в файле.
FIELD A Любое 1 Нет В настоящее время не используется
FIELD B Любое 64 Нет В настоящее время не используется
FIELD C Любое 128 Нет В настоящее время не используется
FIELD D Любое 256 Нет В настоящее время не используется
FIELD E Любое 11 Нет В настоящее время не используется
FIELD F Любое 12 Нет В настоящее время не используется
API-интерфейс возвращает ответ в формате XML, который подходит для использования в большом количестве программ и языков программирования.

Пример ответа в формате XML от API-интерфейса при поиске BIC будет выглядеть следующим образом:


<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-формы.

Ниже представлено подробное описание всех возможных ошибок:

Status Code Тип Описание
301 Ошибка учетной записи Неправильный API-ключ
302 Ошибка учетной записи Истек срок действия подписки
303 Ошибка учетной записи Нет доступных записей
304 Ошибка учетной записи У вас нет доступа к API
401 Ошибка ввода Максимальная длина SWIFT составляет 8 или 11 символов'
402 Ошибка ввода Неправильное наименование банка. Может содержать не менее 4 символов.
Доступные значения: a-z, A-Z, 0-9, [пробел]!
403 Ошибка ввода Неправильный код страны! Необходимо использовать двухзначный код. Например: UK, DE, FR