Подключение к API

Требования к организации подключения

Модель взаимодействия

API использует модель RESTful (данные передаются в виде объектов JSON). Особенностью является использование двунаправленной модели соединения, заключающейся в том, что любое взаимодействие между Cardsmobile и эмитентом производится следующим образом:

  1. Сторона A (например — эмитент) инициирует запрос API и направляет его стороне B (например — платформе Cardsmobile).

  2. Сторона B принимает запрос и в случае успешной обработки возвращает HTTP-ответ с кодом 200 и пустое тело сообщения при отсутствии ошибки в обработке запроса, либо, при наличии ошибки, HTTP-ответ с необходимым кодом и объектом ErrorDescription в теле сообщения.

  3. При отсутствии ошибки вслед за этим сторона B формирует запрос API, содержащий ответ на запрос стороны A и отправляет его стороне A.

  4. Сторона A принимает запрос от B и в случае успешной обработки возвращает HTTP-ответ с кодом 200 и пустое тело сообщения при отсутствии ошибки в обработке запроса, либо, при наличии ошибки, HTTP-ответ с необходимым кодом и объектом ErrorDescription в теле сообщения.

В рамках одного акта взаимодействия между клиентами передается сквозной идентификатор запроса продукта (поле productRequestId). Значение productRequestId формируется на стороне Cardsmobile в рамках запроса на выпуск продукта.

Взаимодействие эмитента и Cardsmobile

Cardsmobile должен предоставить эмитенту следующие данные:

Параметр

Описание

issuerId

Идентификатор эмитента на сервере Кошелька.

productId

Идентификатор карточного продукта эмитента на сервере Кошелька.

URL тестового подключения к Cardsmobile

Используется эмитентом для отправки тестовых запросов API.

URL оперативного подключения к Cardsmobile

Используется эмитентом для отправки реальных запросов API.

Эмитент должен предоставить Cardsmobile следующие данные:

Параметр

Описание

URL тестового подключения к эмитенту

Используется Cardsmobile для отправки тестовых запросов API эмитенту.

URL оперативного подключения к эмитенту

Используется Cardsmobile для отправки реальных запросов API эмитенту.

Организация безопасной среды обмена данными

Для обеспечения безопасного обмена данными посредством API, эмитенту необходимо получить от Cardsmobile четыре сертификата (два сертификата для тестового подключения и два сертификата для оперативного подключения). Для этого представитель эмитента должен сформировать и передать офицеру безопасности Cardsmobile запросы на создание подписанных сертификатов (Certificate Signing Request — CSR).

CSR для тестового подключения должны передаваться в незащищенном ZIP-архиве, а CSR для оперативного подключения — в ZIP-архиве, защищенном с использованием общего пароля, которым заранее обменялись офицеры безопасности эмитента и Cardsmobile.

1. Запросы на сертификат для Gateway Public Key – открытого ключа эмитента, используемого для защиты транспортного уровня по протоколу TLS 1.2.

Параметры сертификата:

Для тестового подключения
Для оперативного подключения
Для тестового подключения

Параметр сертификата

Значение

CN

"Inbound Gateway TEST".

O

Имя эмитента.

OU

"Issuer-" + доп. сведения (отдел, подразделение и т.п.).

C

Двухбуквенный код страны (по ISO 3166-1 alpha-2).

Для оперативного подключения

Параметр сертификата

Значение

CN

"Inbound Gateway PROD".

O

Имя эмитента.

OU

"Issuer-" + доп. сведения (отдел, подразделение и т.п.).

C

Двухбуквенный код страны (по ISO 3166-1 alpha-2).

2. Запросы на сертификат для Issuer Wrapping Public Key – открытого ключа эмитента, используемого для шифрования одноразового RGK-ключа в запросах API, содержащих чувствительные данные (данные банковской карты).

Параметры сертификата:

Для тестового подключения
Для оперативного подключения
Для тестового подключения

Параметр сертификата

Значение

CN

Имя эмитента + доп. идентификатор (не FQDN узла эмитента!).

O

Имя эмитента.

OU

"Issuer Outbound Encryption TEST".

C

Двухбуквенный код страны (по ISO 3166-1 alpha-2).

Для оперативного подключения

Параметр сертификата

Значение

CN

Имя эмитента + доп. идентификатор (не FQDN узла эмитента!).

O

Имя эмитента.

OU

"Issuer Outbound Encryption PROD".

C

Двухбуквенный код страны (по ISO 3166-1 alpha-2).

Используемая длина ключа RSA — 2048 бит.

После обработки полученных CSR, офицер безопасности Cardsmobile вернет офицеру безопасности эмитента подписанные сертификаты, необходимые для работы с API в соответствующих ZIP-архивах (архив, содержащий сертификаты для оперативного подключения, будет защищен общим для эмитента и Cardsmobile паролем):

  1. Подписанный сертификат эмитента для Gateway Public Key и сертификат Cardsmobile, содержащий соответствующий открытый ключ Cardsmobile;

  2. Подписанный сертификат эмитента для Issuer Wrapping Public Key и сертификат Cardsmobile, содержащий соответствующий открытый ключ Cardsmobile.