1 Использование INAPP API
2 Транспорт и протокол
3 Общие положения
4 Коды ответа
5 Коды ошибок и их описание
- 5.1 Объект ошибки
6 Регистрация
- 6.1 Регистрация
  - 6.1.1 Формат запроса
  - 6.1.2 Формат ответа
- 6.2 Верификация
  - 6.2.1 Формат запроса
  - 6.2.2 Формат ответа
- 6.3 Установка ПИН-кода
  - 6.3.1 Формат запроса
  - 6.3.2 Формат ответа
- 6.4 Повторная отправка СМС
  - 6.4.1 Формат запроса
7 Вход с другого устройства
- 7.1 Формат запроса
- 7.2 Формат ответа
8 Аутентификация
- 8.1 Аутентификация
  - 8.1.1 Формат запроса
  - 8.1.2 Формат ответа
- 8.2 Обновление токена
  - 8.2.1 Формат запроса
  - 8.2.2 Формат ответа
9 Прикрепление банковской карты
- 9.1 Прикрепление банковской карты
  - 9.1.1 Формат запроса
  - 9.1.2 Формат ответа
- 9.2 Проверка статуса
  - 9.2.1 Формат запроса
  - 9.2.2 Формат ответа
- 9.3 Получение 3D Secure страницы
  - 9.3.1 Формат запроса
  - 9.3.2 Формат ответа
- 9.4 Получение списка карт
  - 9.4.1 Формат запроса
  - 9.4.2 Формат ответа
10 Смена приоритета карты
- 10.1 Формат запроса
- 10.2 Формат запроса
11 Удаление банковской карты
- 11.1 Формат запроса
12 Оплата в приложении
- 12.1 Создание заказа
- 12.2 Формат запроса
- 12.3 Формат ответа
- 12.4 Оплата заказа
  - 12.4.1 Формат запроса
  - 12.4.2 Формат ответа
- 12.5 Получение статуса оплаты
  - 12.5.1 Формат запроса
  - 12.5.2 Формат ответа

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

INAPP API - программный интерфейс для оплаты покупок в приложении SWiP.

Транспорт и протокол

В качестве транспорта использует HTTPS протокол. Сообщения кодируются в JSON формат.

Общие положения

Для выполнения большинства запросов необходима аутентификация. Запрос должен содержать заголовок X-Auth-Token, значением которого является JWT-токен.

Список заголовков, которые необходимо обязательно передавать в API запросах:

Название поля	Пример значения	Описание

Название поля	Пример значения	Описание
X-Auth-Token	eyJhbGciOiJIUzUxMM....9rZ8VQ54JqWFe1Q	Токен приходит после регистрации или после входа в приложение.
Api-Version	2	Версия API.

Коды ответа

HTTP-код	Описание	Код ошибки

HTTP-код	Описание	Код ошибки
200	Успешный запрос.
400	Неправильный запрос из-за нарушения правил взаимодействия с API.	bad_request
401	Неудачная авторизация.	unauthorized
403	Доступ запрещен.	forbidden
404	Ресурс по указанному id не был найден в системе SWiP.	not_found
405	Используется запрещенный или неподдерживаемый метод.	method_not_allowed
429	Отправлено слишком много запросов за короткий промежуток времени.	too_many_request
500	Внутренняя ошибка сервера.	internal_server_error

Коды ошибок и их описание

Код ошибки	Описание

Код ошибки	Описание
1	INTERNAL SERVER ERROR Внутренняя ошибка сервера.
2	AUTHENTICATION ERROR Неудачная аутентификация.
4	ACCESS DENIED Доступ запрещен.
5	VALIDATION FAILED Некорректная валидация.
6	ILLEGAL STATE Ошибка неправильного состояния текущей операции.
7	METHOD NOT SUPPORTED Метод не поддерживается.
8	DUPLICATE Дублицирование данных.
9	NOT FOUND Ресурс не найден.
10	UNSUPPORTED MESSAGE Неподдерживаемое сообщение.
11	ORDER FLOW VIOLATION Нарушение процесса обработки заказа.
12	SMS CODE EXPIRED Истек срок действия СМС-кода.
13	OPERATION TIMED OUT Истекло время ожидания операции.
14	DOESNT MATCH Несовпадение данных.
15	PAYMENTS BLOCKED Платежи заблокированы.
16	TOKEN EXPIRED Истек срок действия JWT токена.
17	JWT TOKEN ERROR Ошибка процессинга токена.
18	CONCURRENT PAYMENT ERROR Ошибка из-за осуществления параллельных платежей.
19	BANK PAYMENT ERROR Ошибка оплаты банка.
20	PAYMENT CARD BLOCKED Платежная карта заблокирована.
21	ACCOUNTING ERROR Ошибка в расчетах.
22	REQUEST LIMIT EXCEEDED Превышен лимит количества запросов.
23	EXTERNAL SYSTEM ERROR Внешняя ошибка системы.
24	CASHBACK PAYMENT ERROR Ошибка при оплате кэшбэком.
25	OPERATION IN PROGRESS Операция находится в процессе выполнения.
26	CUSTOMER DUPLICATE PIN Дублицирование ПИН-кода клиента.
27	REVERSE UNAVAILABLE Отмена оплаты недоступна.
28	ORDER ALREADY EXISTS Заказ уже существует.
29	ORDER ALREADY REFUNDED Возврат по заказу уже выполнен.
30	ORDER ALREADY CONFIRMED Подтверждение оплаты заказа уже выполнено.
31	ORDER NOT PAID Ордер не оплачен.
32	EXCESS TOTAL AMOUNT Попытка вернуть сумму превышающую сумму заказа.

Объект ошибки

Если при выполнении запроса произошла ошибка, вернется следующий объект:

{
  "code": 0,                        // код внутренней ошибки SWiP
  "description": "string",          // описание ошибки
  "fieldErrors": [                  // массив объектов с детальным описанием
    {
      "field": "string",            // поле, в котором произошла ошибка
      "message": "string",          // детали ошибки
      "objectName": "string"        // класс объекта, у которого произошла ошибка
    }
  ]
}

Регистрация

Пользователь регистрируется по номеру телефона с подтверждением по СМС. Сообщение на указанный номер телефона может быть отправлено не более одного раза в минуту.

Регистрация

Формат запроса

POST /v2/signups

Для регистрации нового пользователя необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`phone`	string, обязательный	Номер телефона, на который регистрируется приложение.

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

{"phone":"string"} // номер телефона в виде 11-ти цифр

Формат ответа

В ответ на запрос приходит токен для аутентификации.

Пример тела ответа

{  
   "token":"eyJhbGciOi...OsCJZDnxqQg",
   "refreshToken":null,
   "refreshPeriod":3600,
   "tokenRefreshPeriod":3600
}

Верификация

Чтобы завершить регистрацию, системе необходимо убедиться, что пользователь указал существующий номер телефона.

Формат запроса

POST /v2/signup-verifications

Для верификации номера телефона пользователя отправляется запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`code`	string, обязательный	Код, который приходит в СМС-сообщении от SWiP.

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

{"code":"6826"}

Формат ответа

В ответ на запрос приходит объект, который говорит о том, что такой номер телефона в базе ещё не зарегистрирован. Этот ответ означает, что необходимо перейти к установке ПИН-кода.

Пример тела ответа

{"new":true}

Установка ПИН-кода

Вызывает метод установки ПИН-кода.

На данный момент возможность восстановления ПИН-кода не реализована. Если пользователь его забыл, необходимо обратиться в службу поддержки.

Формат запроса

PUT v2/signups

Для установки ПИН-кода отправляется запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`deviceId`	string, обязательный	Идентификатор устройства.
`firstName`	string, необязательный	Имя пользователя.
`lastName`	string, необязательный	Фамилия пользователя.
`password`	string, обязательный	ПИН-код, который ввел пользователь.

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

{
  "deviceId": "string",
  "firstName": "string",
  "lastName": "string",
  "password": "string"
}

Формат ответа

В ответ на запрос приходит токен и рефреш токен, с которыми приложение может делать запросы аутентификации.

Пример тела ответа

{  
   "token":"eyHkl...J67g",
   "refreshToken":"eyJhb...36pvFFw",
   "refreshPeriod":3600,
   "tokenRefreshPeriod":3600
}

Повторная отправка СМС

Запрашивает метод для повторной отправки СМС. Необходим, если на мобильный телефон не пришло сообщение с кодом для верификации.

Формат запроса

POST /sms-messages

В качестве ответа используется HTTP-код.

Вход с другого устройства

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

Формат запроса

POST /v2/signup-devices

Для входа с другого устройства или после переустановки приложения необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`deviceId`	string, обязательный	Идентификатор устройства.
`password`	string, обязательный	ПИН-код, который ввел пользователь.

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

{
  "deviceId": "string",
  "password": "string"
}

Формат ответа

В ответ на запрос приходит токен.

Пример тела ответа

{
  "refreshPeriod": 0,
  "refreshToken": "string",
  "token": "string",
  "tokenRefreshPeriod": 0
}

Аутентификация

Аутентификация происходит после перезапуска или после бездействия в приложении.

Аутентификация

Формат запроса

POST /auth

Для получения токена необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`deviceId`	string, обязательный	Идентификатор устройства.
`password`	string, обязательный	ПИН-код, который ввел пользователь.
`username`	string, обязательный	Номер телефона указанный при регистрации.

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

{  
   "deviceId":"9e044ffccc5d0916",
   "password":"1111",
   "username":"string"
}

Формат ответа

В ответ на запрос приходит следующий объект.

Пример тела ответа

{  
   "token":"eyJhbG....Wnp--Q",
   "refreshToken":"eyJhbG.....fW9Gw",
   "refreshPeriod":3600,
   "tokenRefreshPeriod":3600,
   "stpStatus":"OFF",
   "deviceRegistrationRequired":false
}

Полученный токен действителен в течение 1 часа и не требует повторного запроса при каждой операции. По истечении его срока действия приходит ошибка. Чтобы продолжить работу необходимо отправить запрос на получение токена. Для этого нужно либо заново пройти процедуру аутентификации либо обновить токен, используя refreshToken.

Обновление токена

Токен можно обновить до окончания срока действия следующим запросом.

Формат запроса

PUT /auth

Формат ответа

В ответ на запрос приходит токен.

Пример тела ответа

{  
   "token":"eyHkl...J67g",
   "refreshToken":"eyJhb...36pvFFw",
   "refreshPeriod":3600,
   "tokenRefreshPeriod":3600
}

Прикрепление банковской карты

Прикрепление карты необходимо для совершения платежей, а также для проверки того, что пользователь имеет доступ к данной карте (списание контрольной суммы, проверка через 3DS).

Прикрепление банковской карты

Формат запроса

POST /payment-cards

Для прикрепления банковской карты необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`addAsDefault`	boolean, обязательный	Использование карты по умолчанию.
`holder`	string, обязательный	Имя держателя карты.
`cryptogram`	string, обязательный	Зашифрованные данные карты (год и месяц окончания срока действия карты, номер карты, CVV).

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

{  
   "addAsDefault":true,
   "holder":"cardholder name",
   "cryptogram":"string"
}

Формат ответа

В ответ на запрос приходит временный идентификатор карты.

Пример тела ответа

{"deferredId":"d83a617e-dae3-448b-875d-c62d163b030a"}

Проверка статуса

Запрос позволяет получить текущий статус привязки карты и идет в цикле c интервалом в одну секунду.

Формат запроса

GET /deferred-results/{id}/status

Для получения текущего статуса по привязке карты необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`id`	string, обязательный	Временный идентификатор, по которому можно получить статус прикрепления карты.

Формат ответа

В ответ на запрос приходит текущий статус привязки карты.

Пример тела ответа

{  
   "status":"PROCESSING",
   "errorCode":"",
   "errorMessage":""
}

Поле status может принимать следующие значения:

Значение	Описание

Значение	Описание
`FAIL`	Карту не удалось прикрепить.
`SUCCESS`	Карта успешно прикреплена.
`PROCESSING`	Данные по карте обрабатываются.
`FINISH_3DS`	Требуется ввод проверочного кода для подтверждение прикрепления карты.

Получение 3D Secure страницы

Прикрепление карты проводится с применением технологии 3D Secure. После ввода проверочного кода временно блокируется 1 рубль на указанной банковской карте. Через некоторое время блокировка суммы снимается эмитентом карты.

Формат запроса

GET /deferred-results/{id}/binding-payment-card-3ds-result

Для получения 3D Secure страницы необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`id`	string, обязательный	Временный идентификатор карты.

Формат ответа

В ответ на запрос приходит HTML-код страницы, которая содержит форму для ввода проверочного кода от банка.

Пример тела ответа

1
2
3

{  
   "finish3dsHtml":"<!DOCTYPE html>\n<html>...HTML code...</html>"
}

Получение списка карт

Запрашивает список прикрепленных карт.

Формат запроса

GET /payment-cards

Формат ответа

В ответ приходит список прикрепленных карт.

Пример тела ответа

[  
   {  
      "id":"730818ac-4b3c-4356-b1dd-783a3d5ff676",        // идентификатор карты в системе SWiP
      "cardNumber":"**** **** **** 2009",                 // номер карты
      "defaultForPayments":true,                          // использование карты по умолчанию
      "bankName":"Название банка",                        // название банка
      "bankLogo":"471b8f50-bb8d-11e6-9a11-08a47b0e7ea4",  // логотип банка
      "paymentSystem":"VISA",                             // платежная система
      "createdAt":1543760701775,                          // время создания (в миллисекундах с 01.01.1970)
      "blocked":false                                     // блокировка карты
   },
  {  
      "id":"767818ac-4b3c-8567-b1dd-784r56ff676",
      "cardNumber":"**** **** **** 1209",
      "defaultForPayments":false,
      "bankName":"Название банка",
      "bankLogo":"501b8f50-bb8d-48e6-9a11-08a47b0e7ea4",
      "paymentSystem":"МИР",
      "createdAt":1543760702376,
      "blocked":false
   }
]

Смена приоритета карты

Первая добавленная в SWiP карта выбирается для использования по умолчанию.

Формат запроса

Если добавлено несколько карт и пользователь хочет изменить карту по умолчанию, следует выполнить следующий запрос.

POST /payment-cards/{id}/actions/set-as-default

Для выбора карты по умолчанию необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`id`	string, обязательный	Идентификатор банковской карты в системе SWiP.

В качестве ответа используется HTTP-код.

Формат запроса

Если добавлено несколько карт и пользователь хочет отменить выбор карты по умолчанию, следует выполнить следующий запрос.

POST /payment-cards/{id}/actions/unset-as-default

Для отключения карты по умолчанию необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`id`	string, обязательный	Идентификатор банковской карты в системе SWiP.

В качестве ответа используется HTTP-код.

Удаление банковской карты

Запрашивает удаление банковской карты на сервере SWiP.

Формат запроса

DELETE /payment-cards/{id}

Для удаления банковской карты необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`id`	string, обязательный	Идентификатор карты в системе SWiP.

Оплата в приложении

Создание заказа

Чтобы оплатить покупку в приложении, необходимо создать заказ.

Формат запроса

POST /inapp-orders

Для создания заказа необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`merchantId`	string, обязательный	Идентификатор мерчанта в системе SWiP.
`merchantStoreId`	string, обязательный	Идентификатор магазина мерчанта в системе SWiP.
`purchases`	list, обязательный	Список покупок.
`productId`	string, обязательный	Идентификатор товара.
`quantity`	double, обязательный	Количество товара.

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

{
  "merchantId": "string",
  "merchantStoreId": "string",
  "purchases": [
    {
      "productId": "string",
      "quantity": 0
    }
  ]
}

Формат ответа

В ответ на запрос приходит заказ в актуальном статусе.

Пример тела ответа

{
  "cashOrigin": "IIKO",
  "cashback": 0,
  "cashbackCalcResult": {
    "lines": [
      {
        "campaignId": "string",
        "cashback": 0,
        "cboRequiredCount": 0,
        "description": "string",
        "purchaseCount": 0
      }
    ],
    "total": 0
  },
  "classifier": "OK",
  "customerId": "string",
  "discount": {
    "discount": 0,
    "discountOriginal": 0,
    "lines": [
      {
        "campaignId": "string",
        "cboRequiredCount": 0,
        "description": "string",
        "discount": 0,
        "purchaseCount": 0
      }
    ]
  },
  "emailRequired": true,
  "externalLoyalty": {
    "merchantPoints": 0,
    "points": {
      "added": 0,
      "removed": 0,
      "total": 0
    }
  },
  "id": "string",
  "merchantCash": "string",
  "merchantCashier": "string",
  "merchantCashierId": "string",
  "merchantCategory": "string",
  "merchantId": "string",
  "merchantName": "string",
  "merchantOrderId": "string",
  "merchantOrderNumber": "string",
  "merchantProfileImageId": "string",
  "merchantStore": "string",
  "orderNumber": "string",
  "orderStatus": "NEW",
  "purchases": [
    {
      "amount": 0,
      "discount": 0,
      "id": "string",
      "merchantDiscount": 0,
      "name": "string",
      "price": 0,
      "productId": "string",
      "quantity": 0,
      "unit": "string"
    }
  ],
  "saleDate": 0,
  "sessionCode": "string",
  "total": 0,
  "totalOriginal": 0
}

Оплата заказа

Формат запроса

POST /orders/{id}/payments

Для оплаты заказа необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`id`	string, обязательный	Идентификатор заказа в системе SWiP.
`paymentCardId`	string, обязательный	Идентификатор карты, с которой производится оплата.
`email`	string, обязательный	Электронный адрес пользователя.

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

{
  "email": "string",
  "paymentCardId": "30c02942-0a7f-4977-bd48-50dd4353c3e0"
}

Формат ответа

В ответ на запрос приходит временный идентификатор чека.

Пример тела ответа

{"deferredId":"426a58d6-7f7c-4155-8c6b-e5242bcc5e69"}

Получение статуса оплаты

Запрос позволяет получить текущий статус оплаты и идет в цикле с интервалом в одну секунду.

Формат запроса

GET /deferred-results/{deferredId}/status

Для получения статуса оплаты необходимо отправить запрос с передачей следующих параметров:

Параметр	Тип	Описание

Параметр	Тип	Описание
`deferredId`	string, обязательный	Временный идентификатор чека.

Формат ответа

В ответ на запрос приходит статус оплаты.

Пример тела ответа

{ 
   "status":"PROCESSING",
   "errorCode":"",
   "errorMessage":""
}

Поле status может принимать следующие значения:

Значение	Описание

Значение	Описание
`PROCESSING`	Оплата заказа находится в обработке.
`SUCCESS`	Оплата прошла успешно.
`FAIL`	Оплата не прошла.
`LOYALTY_CALCULATION`	Расчет лояльности.

API оплаты в приложении

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

Транспорт и протокол

Общие положения

Коды ответа

Коды ошибок и их описание

Объект ошибки

Регистрация

Регистрация

Формат запроса

Формат ответа

Верификация

Формат запроса

Формат ответа

Установка ПИН-кода

Формат запроса

Формат ответа

Повторная отправка СМС

Формат запроса

Вход с другого устройства

Формат запроса

Формат ответа

Аутентификация

Аутентификация

Формат запроса

Формат ответа

Обновление токена

Формат запроса

Формат ответа

Прикрепление банковской карты

Прикрепление банковской карты

Формат запроса

Формат ответа

Проверка статуса

Формат запроса

Формат ответа

Получение 3D Secure страницы

Формат запроса

Формат ответа

Получение списка карт

Формат запроса

Формат ответа

Смена приоритета карты

Формат запроса

Формат запроса

Удаление банковской карты

Формат запроса

Оплата в приложении

Создание заказа

Формат запроса

Формат ответа

Оплата заказа

Формат запроса

Формат ответа

Получение статуса оплаты

Формат запроса

Формат ответа