Запросы API

Запросы Cardsmobile к эмитенту и эмитента к Cardsmobile при выпуске и обслуживании экземпляра продукта

post
Запрос на выпуск экземпляра продукта пользователю

https://<issuer-URL>/product/form/requestProduct
Этот запрос позволяет передать эмитенту сведения о пользователе, выпускающем банковскую карту в свой «Кошелёк».
Request
Response
Request
Body Parameters
productRequestId
required
string
Идентификатор запроса продукта.
productId
required
string
Идентификатор, присвоенный продукту Cardsmobile.
platform
required
string
ОС мобильного устройства пользователя. Предопределенные значения: ANDROID, IOS.
form
optional
object
Поля заполненной пользователем анкеты (набор пар ключ = значение).
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от Cardsmobile к эмитенту.

Пример тела запроса:

{
"productRequestId": "4ee64eb1-0012-4cd0-aefe-966d48ea7b71",
"productId": "AAA_1",
"platform": "ANDROID",
"form": {...}
}

post
Ответ на запрос выпуска экземпляра продукта со стороны эмитента

https://<CM-URL>/product/form/notifyRequestProductResult
Запрос, вызываемый со стороны эмитента после обработки анкеты пользователя, переданной со стороны Cardsmobile запросом requestProduct.
Request
Response
Request
Body Parameters
productRequestId
required
string
Идентификатор запроса продукта.
issuerId
required
integer
Идентификатор эмитента.
status
required
string
Статус заявки на выпуск карты. Используются только предопределенные значения: APPROVED — заявка на выпуск одобрена эмитентом; DECLINED — заявка отклонена эмитентом;AUTHENTICATION_REQUIRED — требуется дополнительная аутентификация клиента.
authenticationMethods
optional
array
Перечень допустимых методов аутентификации в виде массива объектов AuthenticationMethod.
userMessage
optional
string
Дополнительное сообщение пользователю от эмитента. Например, необходимо предоставить документы или заполнить анкету снова из-за обнаруженных ошибок в предыдущей анкете и т. д. Длина сообщения – не более 2000 символов, кодировка – UTF-8.
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от эмитента к Cardsmobile.

Пример тела запроса:

{
"productRequestId": "4ee64eb1-0012-4cd0-aefe-966d48ea7b71",
"issuerId": 5,
"status": "AUTHENTICATION_REQUIRED",
"authenticationMethods": [
{
"methodId": 4,
"type": "WEB_LINK",
"value": "https://my-bank/card"
}
]
"userMessage": "Требуется дополнительная аутентификация пользователя"
}

См. описание объекта AuthenticationMethod.

post
Передача эмитенту способа аутентификации, выбранного пользователем

https://<issuer-URL>/product/form/authentication/selectedMethod
Метод используется, если ранее от эмитента был получен запрос notifyRequestProductResult с полем status, установленным в значение AUTHENTICATION_REQUIRED и пользователь произвел выбор метода аутентификации из предложенных эмитентом.
Request
Response
Request
Body Parameters
productRequestId
required
string
Идентификатор запроса продукта.
methodId
required
number
Идентификатор выбранного метода аутентификации.
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от Cardsmobile к эмитенту. Перечень допустимых методов идентификации предварительно согласовывается эмитентом и Cardsmobile.

Пример тела запроса:

{
"productRequestId": "4ee64eb1-0012-4cd0-aefe-966d48ea7b71",
"methodId": 2
}

post
Передача ответа пользователя в рамках проверки аутентификации

https://<CM-URL>/product/form/authentication/authenticate
Метод используется в случае если в запросе notifyRequestProductResult поле status имеет значение AUTHENTICATION_REQUIRED, а поле authenticationMethod — значение OTP_CODE.
Request
Response
Request
Body Parameters
productRequestId
required
string
Идентификатор запроса продукта.
value
required
string
Одноразовый код аутентификации (OTP), введенный пользователем.
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от Cardsmobile к эмитенту.

Пример тела запроса:

{
"productRequestId": "4ee64eb1-0012-4cd0-aefe-966d48ea7b71",
"value": "12345"
}

post
Запрос доставки продукта пользователю со стороны Cardsmobile

https://<issuer-URL>/product/provision/provisionRequest
Метод позволяет платформе Cardsmobile запросить у эмитента загрузку в телефон пользователя (в мобильное приложение «Кошелёк» либо в Apple Wallet) экземпляра продукта, выпущенного эмитентом.
Request
Response
Request
Body Parameters
productRequestId
required
string
Идентификатор запроса продукта.
encryptedPayload
optional
object
Зашифрованный одноразовый открытый ключ мобильного приложения получателя в виде объекта EncryptedPayload.
appleWalletProvisionRequest
optional
object
Запрос на загрузку экземпляра продукта в Apple Wallet (формируется согласно инструкциям Apple, актуально только для устройств на iOS).
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от Cardsmobile к эмитенту.

Пример тела запроса:

{
"productRequestId": "4ee64eb1-0012-4cd0-aefe-966d48ea7b71",
"appleWalletProvisionRequest": {},
"encryptedPayload": {}
}

Передача зашифрованных данных

Поле encryptedPayload заполняется только в случае, если ожидается, что эмитент будет передавать Cardsmobile в ответном запросе чувствительные данные карты, например — проверочный код CVC2/CVV2. Расшифрованное значение поля encryptedData объекта EncryptedPayload имеет вид объекта JSON:

{
"appOneTimePublicKey": "<значение ключа>"
}

где appOneTimePublicKey — одноразовый открытый ключ экземпляра мобильного приложения «Кошелёк».

Поле appleWalletProvisionRequest заполняется только в случае, если выпущенный экземпляр продукта подлежит загрузке в Apple Wallet.

post
Ответ эмитента на запрос на загрузку карты

https://<CM-URL>/product/provision/provisionResult
Запрос, направляемый эмитентом в Cardsmobile. Содержит данные экземпляра банковского продукта для выпуска в мобильном приложении «Кошелёк» либо в приложении Apple Wallet.
Request
Response
Request
Body Parameters
productRequestId
required
string
Идентификатор запроса продукта.
productInstanceId
required
string
Идентификатор экземпляра продукта.
issuerId
required
integer
Идентификатор эмитента.
encryptedPayload1
required
object
Зашифрованные сведения о выпущенном продукте в виде объекта EncryptedPayload.
encryptedPayload2
optional
object
Зашифрованное значение контрольного кода CVN (CVC2/CVV2) в виде объекта EncryptedPayload.
appleWalletProvisionRespons
optional
string
Строка для выпуска экземпляра продукта в Apple Wallet (формируется согласно инструкциям Apple, актуально только для устройств на iOS).
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от эмитента к Cardsmobile.

Пример тела запроса:

{
"productRequestId": "4ee64eb1-0012-4cd0-aefe-966d48ea7b71",
"productInstanceId": "cf94bc49-333b-491a-ba8b-9329849ed7e5",
"issuerId": 5,
"encryptedPayload1": {...},
"encryptedPayload2": {...},
"appleWalletProvisionResponse": ""
}

Передача зашифрованных данных

В поле encryptedPayload1 передается объект EncryptedPayload, расшифрованное значение поля encryptedData которого имеет вид объекта JSON:

Имя

Тип

Описание

type

String

Тип банковского продукта, например: BANK_CARD.

pan

String

PAN (Номер банковской карты), если type=BANK_CARD.

expDate

String

Дата окончания действия карты, если type=BANK_CARD.

statusId

String

Идентификатор статуса карты, если type=BANK_CARD.

cardHolderName

String

Имя владельца карты, если type=BANK_CARD.

Пример расшифрованного значения encryptedPayload1.encryptedData:

{
"type": "BANK_CARD",
"pan": "1111 1111 1111 1111",
"expDate": "01/23",
"statusId": "2",
"cardHolderName": "IVAN IVANOV"
}

По согласованию с эмитентом, набор передаваемых в запросе полей может быть дополнен. Например, это может быть использовано в следующих ситуациях:

  • Для передачи идентификатора клиента в системе лояльности ритейлера для обладателя выпускаемой банковской карты, если она — кобрендинговая, то есть совмещена с картой лояльности ритейлера,

  • Для передачи TAV (Tokenization Authentication Value) для последующей токенизации выпущенной виртуальной карты по «зеленому» пути.

Поле encryptedPayload2 передается только если эмитент сообщает Cardsmobile контрольный код CVN (CVC2/CVV2). В этом поле передается объект EncryptedPayload, расшифрованное значение поля encryptedData которого имеет вид объекта JSON:

{
"value": "<значение CVN>"
}

Ключ RGK для объекта в поле encryptedPayload2 должен быть зашифрован одноразовым открытым ключом, отправленным эмитенту от Cardsmobile в поле appOneTimePublicKey зашифрованного объекта, переданного в запросе provisionRequest. В этом случае поле encryptedPayload2.encryptedData возможно расшифровать только на в экземпляре мобильного приложения «Кошелёк», работающем на устройстве пользователя-получателя сведений о карте.

Поле encryptedPayload1.encryptedData возможно расшифровать только на узле Cardsmobile.

post
Запрос клиентом данных карты по альтернативным каналам

https://<issuer-URL>/product/instance/requestProductInfo
Запрос, который передается эмитенту, если пользователь запросил передать ему данные выпущенного продукта.
Request
Response
Request
Body Parameters
productRequestId
optional
string
Идентификатор запроса продукта.
productInstanceId
required
string
Идентификатор экземпляра продукта.
deliveryMethodId
required
integer
Идентификатор способа доставки данных пользователю. Предопределенный эмитентом список. Согласовывается эмитентом и Cardsmobile при подготовке к интеграции.
requestedParamIds
required
integer
Перечень идентификаторов запрашиваемых параметров продукта (массив). Возможные значения: 1 — PAN; 2 — дата окончания действия; 3 — имя владельца; 4 — CVN (CVC2/CVV2); 5 — статус; 6 — PIN-код.
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от Cardsmobile к эмитенту. Необязательный запрос.

Пример тела запроса:

{
"productRequestId": "4ee64eb1-0012-4cd0-aefe-966d48ea7b71",
"productInstanceId": "cf94bc49-333b-491a-ba8b-9329849ed7e5",
"deliveryMethodId": 2,
"requestedParamIds": [1, 3]
}

В случае использование этого запроса при взаимодействии с Cardsmobile, эмитент должен определить варианты доставки пользователю информации по продукту. При необходимости перечень идентификаторов может быть дополнен.

post
Оповещение об изменении статуса выпущенного экземпляра продукта со стороны эмитента

https://<CM-URL>/product/instance/notifyProductInstanceUpdated
Запрос, который может быть отправлен эмитентом, если эмитент изменил статус экземпляра продукта, выпущенного для пользователя.
Request
Response
Request
Body Parameters
requestId
required
string
Идентификатор запроса.
issuerId
required
integer
Идентификатор эмитента.
productInstanceId
required
string
Идентификатор экземпляра продукта.
encryptedPayload
required
object
Зашифрованные сведения о статусе продукта в виде объекта EncryptedPayload.
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от эмитента к Cardsmobile. Необязательный запрос.

Пример тела запроса:

{
"requestId": "896a0038-e2d5-4248-964d-fe6caf9130d9",
"issuerId": 5,
"productInstanceId": "cf94bc49-333b-491a-ba8b-9329849ed7e5",
"encryptedPayload": {...},
}

Передача зашифрованных данных

В поле encryptedPayload передается объект EncryptedPayload, расшифрованное значение поля encryptedData которого имеет вид объекта JSON:

Имя

Тип

Описание

statusId

Integer

Идентификатор статуса экземпляра продукта, в который его перевел эмитент.

userMessage

String

Сообщение пользователю от эмитента (не более 200 символов, кодировка UTF-8).

Пример расшифрованного значения encryptedPayload.encryptedData:

{
"statusId": 3,
"userMessage": "Карта заблокирована"
}

post
Запрос на изменение статуса выпущенного экземпляра продукта со стороны клиента

https://<issuer-URL>/product/instance/сhangeProductInstanceRequest
Запрос, который может быть отправлен эмитенту, если пользователь запрашивает изменение статуса экземпляра продукта, выпущенного для него эмитентом.
Request
Response
Request
Body Parameters
requestId
required
string
Идентификатор запроса.
productInstanceId
required
string
Идентификатор экземпляра продукта.
encryptedPayload
required
object
Зашифрованные сведения о статусе продукта в виде объекта EncryptedPayload.
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от Cardsmobile к эмитенту. Необязательный запрос.

Пример тела запроса:

{
"requestId": "896a0038-e2d5-4248-964d-fe6caf9130d9",
"productInstanceId": "cf94bc49-333b-491a-ba8b-9329849ed7e5",
"encryptedPayload": {...}
}

Передача зашифрованных данных

В поле encryptedPayload передается объект EncryptedPayload, расшифрованное значение поля encryptedData которого имеет вид объекта JSON:

Имя

Тип

Описание

statusId

Integer

Идентификатор статуса экземпляра продукта, который к нему желает применить пользователь.

Пример расшифрованного значения encryptedPayload.encryptedData:

{
"statusId": 3
}

post
Запрос текущего баланса продукта

https://<issuer-URL>/product/instance/statusRequest
Запрос направляется эмитенту для получения сведений о текущем балансе продукта, экземпляр которого выпущен пользователю.
Request
Response
Request
Body Parameters
requestId
required
string
Идентификатор запроса.
productInstanceId
required
string
Идентификатор экземпляра продукта.
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от Cardsmobile к эмитенту. Необязательный запрос.

Пример тела запроса:

{
"requestId": "896a0038-e2d5-4248-964d-fe6caf9130d9",
"productInstanceId": "cf94bc49-333b-491a-ba8b-9329849ed7e5"
}

post
Передача информации по балансу карты

https://<CM-URL>/product/instance/notifyStatusDetails
Запрос от эмитента, содержащий сведения о текущем балансе продукта. Отправляется в ответ на запрос statusRequest.
Request
Response
Request
Body Parameters
requestId
required
string
Идентификатор запроса.
issuerId
required
integer
Идентификатор эмитента.
productInstanceId
required
string
Идентификатор экземпляра продукта.
amount
required
number
Текущий баланс. Число с двумя знаками после запятой (в качестве разделителя используется точка).
currencyCode
required
string
Трехбуквенный код валюты в соответствии со стандартом ISO 4217.
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от эмитента к Cardsmobile. Необязательный запрос.

Пример тела запроса:

{
"requestId": "1e8650dd-b52e-4b6c-b526-75aa6b00cae2",
"issuerId": 5,
"productInstanceId": "cf94bc49-333b-491a-ba8b-9329849ed7e5",
"amount": 631.15,
"currencyCode": "RUB"
}

post
Запрос истории транзакций по продукту

https://<issuer-URL>/product/instance/getTransactionHistory
Запрос направляется эмитенту для получения перечня транзакций по продукту, экземпляр которого выпущен пользователю, за указанный период времени.
Request
Response
Request
Body Parameters
requestId
required
string
Идентификатор запроса.
productInstanceId
required
string
Идентификатор экземпляра продукта.
fromTimestamp
optional
string
Момент времени, начиная с которого должен быть сформирован список выполненных транзакций.
limit
optional
integer
Количество возвращаемых транзакций. Максимально допустимое значение согласовывается с эмитентом.
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от Cardsmobile к эмитенту. Необязательный запрос.

Пример тела запроса:

{
"requestId": "295914cd-2ada-49cd-93ba-172e37e13af5",
"productInstanceId": "cf94bc49-333b-491a-ba8b-9329849ed7e5",
"fromTimestamp": "2019-06-05T18:23:05+03:00",
"limit": 10
}

post
Передача истории транзакций по продукту

https://<CM-URL>/product/instance/notifyTransactionHistory
Запрос от эмитента, содержащий список транзакций продукта. Отправляется в ответ на запрос getTransactionHistory.
Request
Response
Request
Body Parameters
requestId
required
string
Идентификатор запроса.
issuerId
required
integer
Идентификатор эмитента.
productInstanceId
required
string
Идентификатор экземпляра продукта.
productTransactions
required
array
Список транзакций. Массив объектов ProductTransaction (массив может быть пустым).
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от эмитента к Cardsmobile. Необязательный запрос.

Пример тела запроса:

{
"requestId": "d204cd1b-a78a-4ec3-a356-9231dbe57cac",
"issuerId": 2,
"productInstanceId": "cf94bc49-333b-491a-ba8b-9329849ed7e5",
"productTransactions":
[
{
"transactionId": "f477f5e3-5a06-4ea2-a0eb-b2ba12215674",
"transactionType": "PURCHASE",
"amount": 125.87,
"currencyCode": "RUB",
"authorizationStatus": "AUTHORIZED",
"timestamp": "2019-06-05T18:23:05+03:00",
"merchantName": "...",
"merchantType": "5812"
}
]
}

См. описание объекта ProductTransaction.

post
Уведомление о текущей транзакции

https://<CM-URL>/product/instance/notifyActualTransaction
Запрос отправляется эмитентом при регистрации транзакции, выполненной с использованием выпущенного экземпляра продукта. Содержит сведения о транзакции.
Request
Response
Request
Body Parameters
requestId
required
string
Идентификатор запроса.
issuerId
required
integer
Идентификатор эмитента.
productInstanceId
required
string
Идентификатор экземпляра продукта.
productTransaction
required
object
Сведения о транзакции. Объект ProductTransaction.
Response
200: OK
Возвращается в случае успешной обработки запроса. Тело ответа — пустое:
422: Unprocessable Entity
Возвращается в случае любой ошибки обработки запроса. Тело ответа – объект ErrorDescription:
{
"errorCode": "INTERNAL_SERVICE_ERROR",
"descriptions": [
"Описание ошибки 1",
"Описание ошибки 2"
],
"message": "Возникла непредвиденная ошибка"
}

Запрос направляется от эмитента к Cardsmobile. Необязательный запрос.

Пример тела запроса:

{
"requestId": "d204cd1b-a78a-4ec3-a356-9231dbe57cac",
"issuerId": 2,
"productInstanceId": "cf94bc49-333b-491a-ba8b-9329849ed7e5",
"productTransaction":
{
"transactionId": "f477f5e3-5a06-4ea2-a0eb-b2ba12215674",
"transactionType": "PURCHASE",
"amount": 125.87,
"currencyCode": "RUB",
"authorizationStatus": "AUTHORIZED",
"timestamp": "2019-06-05T18:23:05+03:00",
"merchantName": "...",
"merchantType": "5812"
}
}

См. описание объекта ProductTransaction.