Программное обеспечение "Драйвер Сбербанк MSB Android 6"
ВНИМАНИЕ! Начиная с версии 6 приложение не совместимо с предыдущими версиями и требует переустановки и дополнительного приложения от Сбербанка для работы в паре UPOS Native
Принцип работы
Приложение запускает HTTP-сервер на порту 18889 и принимает команды для банковского терминала Сбербанк UPOS, подключённого по USB. Все запросы выполняются асинхронно: сначала запрос ставится в
очередь, а результат запрашивается отдельно по статусу.
Отправка команды
Метод: POST
Адрес: http://127.0.0.1:18889/requests
Заголовок: Content-Type: application/json
Тело запроса — JSON-объект с двумя полями:
uuid — уникальный идентификатор операции, произвольная строка, задаётся вами
request — массив команд, каждая команда — массив строк, первый элемент — название команды, остальные — параметры
Доступные команды
Проверка связи с терминалом
{"uuid":"1","request":[["Ping"]]}
Оплата — сумма в копейках
{"uuid":"2","request":[["Payment","100"]]}
Отмена — сумма в копейках, RRN необязателен
{"uuid":"3","request":[["Cancel","100"]]}
{"uuid":"3","request":[["Cancel","100","222189446975"]]}
Возврат — сумма в копейках, RRN необязателен
{"uuid":"4","request":[["Refund","100"]]}
{"uuid":"4","request":[["Refund","100","222189446975"]]}
Сверка итогов
{"uuid":"5","request":[["Totals"]]}
Краткий отчёт
{"uuid":"6","request":[["BriefReport"]]}
Полный отчёт
{"uuid":"7","request":[["FullReport"]]}
Ответ на отправку команды
Сервер немедленно возвращает подтверждение и ставит команду в обработку:
{"uuid":"1"}
Проверка статуса выполнения
Метод: GET
Адрес: http://127.0.0.1:18889/requests/uuid — вместо uuid подставьте идентификатор вашего запроса
Рекомендуемый интервал опроса: 500 миллисекунд
Структура ответа статуса
Ответ всегда содержит массив results, каждый элемент которого соответствует одной команде из запроса.
Поле status принимает три значения:
wait — команда ещё выполняется, продолжайте опрос
ready — команда выполнена успешно
error — при выполнении произошла ошибка
Поле error содержит объект с полями:
code — числовой код ошибки (0 означает отсутствие ошибки)
description — текстовое описание ошибки
Поле result появляется когда статус ready и содержит массив с результатами операции:
code — код результата от терминала (0 — успех)
slip — текст чека для печати
card — маскированный номер карты (PAN)
rrn — номер ссылки транзакции (12 цифр), используется при отмене или возврате
authcode — код авторизации
Пример успешного ответа для оплаты
{"results":[{"error":{"code":0,"description":"NoErrors"},"status":"ready","result":[{"code":0,"slip":"... текст чека ...","card":"411111******1111","rrn":"222189446975","authcode":"123456"}]}]}
Пример ответа при выполнении
{"results":[{"error":{"code":0,"description":"NoErrors"},"status":"wait"}]}
Пример ответа при ошибке
{"results":[{"error":{"code":994,"description":"Error"},"status":"error"}]}
Коды ошибок
0 — нет ошибок
991 — терминал занят, выполняется другая операция
993 — превышено время ожидания ответа от терминала
994 — ошибка при выполнении операции
995 — пустой ответ или ошибка разбора ответа терминала
997 — в запросе отсутствует поле request
998 — поле request не является массивом
Рекомендации по интеграции
Используйте уникальный uuid для каждой новой операции — по нему ведётся отслеживание результата.
После отправки команды запрашивайте статус каждые 500 мс до получения статуса ready или error.
Поле rrn из ответа на оплату сохраните — оно потребуется для отмены или возврата этой транзакции.
Сервер поддерживает заголовок Access-Control-Allow-Origin: *, поэтому запросы можно выполнять из браузера напрямую.