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

Использование 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
Попытка вернуть сумму превышающую сумму заказа.

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

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

1 2 3 4 5 6 7 8 9 10 11 { "code": 0, // код внутренней ошибки SWiP "description": "string", // описание ошибки "fieldErrors": [ // массив объектов с детальным описанием { "field": "string", // поле, в котором произошла ошибка "message": "string", // детали ошибки "objectName": "string" // класс объекта, у которого произошла ошибка } ] }

Регистрация

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

Регистрация

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

1 POST /v2/signups

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

Параметр

Тип

Описание

Параметр

Тип

Описание

phone

string, обязательный

Номер телефона, на который регистрируется приложение.

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

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

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

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

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

1 2 3 4 5 6 { "token":"eyJhbGciOi...OsCJZDnxqQg", "refreshToken":null, "refreshPeriod":3600, "tokenRefreshPeriod":3600 }

Верификация

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

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

1 POST /v2/signup-verifications

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

Параметр

Тип

Описание

Параметр

Тип

Описание

code

string, обязательный

Код, который приходит в СМС-сообщении от SWiP.

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

1 {"code":"6826"}

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

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

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

1 {"new":true}

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

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

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

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

1 PUT v2/signups

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

Параметр

Тип

Описание

Параметр

Тип

Описание

deviceId

string, обязательный

Идентификатор устройства.

firstName

string, необязательный

Имя пользователя.

lastName

string, необязательный

Фамилия пользователя.

password

string, обязательный

ПИН-код, который ввел пользователь.

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

1 2 3 4 5 6 { "deviceId": "string", "firstName": "string", "lastName": "string", "password": "string" }

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

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

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

1 2 3 4 5 6 { "token":"eyHkl...J67g", "refreshToken":"eyJhb...36pvFFw", "refreshPeriod":3600, "tokenRefreshPeriod":3600 }

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

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

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

1 POST /sms-messages

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

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

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

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

1 POST /v2/signup-devices

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

Параметр

Тип

Описание

Параметр

Тип

Описание

deviceId

string, обязательный

Идентификатор устройства.

password

string, обязательный

ПИН-код, который ввел пользователь.

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

1 2 3 4 { "deviceId": "string", "password": "string" }

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

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

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

1 2 3 4 5 6 { "refreshPeriod": 0, "refreshToken": "string", "token": "string", "tokenRefreshPeriod": 0 }

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

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

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

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

1 POST /auth

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

Параметр

Тип

Описание

Параметр

Тип

Описание

deviceId

string, обязательный

Идентификатор устройства.

password

string, обязательный

ПИН-код, который ввел пользователь.

username

string, обязательный

Номер телефона указанный при регистрации.

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

1 2 3 4 5 { "deviceId":"9e044ffccc5d0916", "password":"1111", "username":"string" }

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

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

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

1 2 3 4 5 6 7 8 { "token":"eyJhbG....Wnp--Q", "refreshToken":"eyJhbG.....fW9Gw", "refreshPeriod":3600, "tokenRefreshPeriod":3600, "stpStatus":"OFF", "deviceRegistrationRequired":false }

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

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

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

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

1 PUT /auth

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

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

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

1 2 3 4 5 6 { "token":"eyHkl...J67g", "refreshToken":"eyJhb...36pvFFw", "refreshPeriod":3600, "tokenRefreshPeriod":3600 }

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

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

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

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

1 POST /payment-cards

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

Параметр

Тип

Описание

Параметр

Тип

Описание

addAsDefault

boolean, обязательный

Использование карты по умолчанию.

holder

string, обязательный

Имя держателя карты.

cryptogram

string, обязательный

Зашифрованные данные карты (год и месяц окончания срока действия карты, номер карты, CVV).

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

1 2 3 4 5 { "addAsDefault":true, "holder":"cardholder name", "cryptogram":"string" }

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

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

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

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

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

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

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

1 GET /deferred-results/{id}/status

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

string, обязательный

Временный идентификатор, по которому можно получить статус прикрепления карты.

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

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

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

1 2 3 4 5 { "status":"PROCESSING", "errorCode":"", "errorMessage":"" }

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

Значение

Описание

Значение

Описание

FAIL

Карту не удалось прикрепить.

SUCCESS

Карта успешно прикреплена.

PROCESSING

Данные по карте обрабатываются.

FINISH_3DS

Требуется ввод проверочного кода для подтверждение прикрепления карты.

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

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

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

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>" }

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

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

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

1 GET /payment-cards

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

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

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 [ { "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 карта выбирается для использования по умолчанию.

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

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

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

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

string, обязательный

Идентификатор банковской карты в системе SWiP.

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

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

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

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

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

string, обязательный

Идентификатор банковской карты в системе SWiP.

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

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

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

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

1 DELETE /payment-cards/{id}

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

string, обязательный

Идентификатор карты в системе SWiP.

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

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

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

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

1 POST /inapp-orders

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

Параметр

Тип

Описание

Параметр

Тип

Описание

merchantId

string, обязательный

Идентификатор мерчанта в системе SWiP.

merchantStoreId

string, обязательный

Идентификатор магазина мерчанта в системе SWiP.

purchases

list, обязательный

Список покупок.

productId

string, обязательный

Идентификатор товара.

quantity

double, обязательный

Количество товара.

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

1 2 3 4 5 6 7 8 9 10 { "merchantId": "string", "merchantStoreId": "string", "purchases": [ { "productId": "string", "quantity": 0 } ] }

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

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

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 { "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 }

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

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

1 POST /orders/{id}/payments

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

string, обязательный

Идентификатор заказа в системе SWiP.

paymentCardId

string, обязательный

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

email

string, обязательный

Электронный адрес пользователя.

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

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

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

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

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

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

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

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

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

1 GET /deferred-results/{deferredId}/status

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

Параметр

Тип

Описание

Параметр

Тип

Описание

deferredId

string, обязательный

Временный идентификатор чека.

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

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

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

1 2 3 4 5 {     "status":"PROCESSING",    "errorCode":"",    "errorMessage":"" }

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

Значение

Описание

Значение

Описание

PROCESSING

Оплата заказа находится в обработке.

SUCCESS

Оплата прошла успешно.

FAIL

Оплата не прошла.

LOYALTY_CALCULATION

Расчет лояльности.