SWiP SDK

Термины и определения

Клиент SWiP SDK (клиент) - программа с графическим интерфейсом, которая устанавливается на кассе самообслуживания.

Сервер SWiP SDK (сервер) - консольное приложение, представляющее собой gRPC сервис, который работает по протоколу SWiP SDK.

STP Gateway - сервер для оплаты по лицу, входящий в SWiP Cloud.

Cash Gateway - сервер для работы с кассой, входящий в SWiP Cloud.

SWIP Cloud - набор связанных сервисов SWiP.

Касса самообслуживания (КСО) - устройство, позволяющее автоматизировать процесс самообслуживания оплаты товара.

Общее описание

SWiP SDK представляет собой описание множества удаленных процедур, сообщений и перечислений gRPC сервиса.

Рекомендуемая схема использования

 

  1. Клиент вызывает удаленную процедуру init() для настройки учетных данных для доступа к сервисам SWiP Cloud. Передает серверу все необходимые параметры. Процедура init() должна быть проведена перед использованием остальных процедур сервера SWiP SDK. Настройки хранятся в оперативной памяти, поэтому вызов процедуры init() требуется выполнять при перезагрузке сервера.

  2. Клиент вызывает удаленную потоковую процедуру createOrder() для создания заказа. Передает серверу данные для формирования заказа со списком покупок. В ответ приходит успешно созданный заказ. Далее идентификатор этого заказа используется для его оплаты и закрытия.

  3. Клиент вызывает удаленную потоковую процедуру getFrameStream() для включения камеры, выполнения и сохранения наилучшего снимка.
    Процедура getFrameStream() возвращает кадры, полученные из видеопотока камеры и статус процесса распознавания. Поток кадров будет прекращен при нахождении подходящего кадра, который содержит лицо и имеет достаточное качество для прохождения процедуры идентификации.
    По истечении таймаута (настраиваемый параметр) поиск лица прекратится и передача потока кадров завершится.

  4. После нахождения лучшего кадра запускается процесс идентификации покупателя. Клиент выполняет удаленную процедуру identify(), передает пустое значение серверу. Процедура возвращает идентификатор покупателя, код возврата.
    Если клиент получает код IDENT_PIN_REQUIRED, то он должен передать ПИН-код, выполнив повторно процедуру identify().

  5. Чтобы передать баллы для списания, клиент выполняет процедуру calculateLoyalty() (только для клиентов, использующих лояльность SWiP).

  6. Клиент вызывает процедуру pay() для оплаты заказа. Передаёт серверу идентификатор оплачиваемого заказа, идентификатор покупателя и сумму для оплаты. В ответ приходит успешно оплаченный заказ.

  7. Клиент вызывает удаленную потоковую процедуру closeOrder() для закрытия заказа. Передает серверу идентификатор закрываемого заказа и сумму для закрытия. В ответ приходит успешно закрытый заказ.

  8. Клиент вызывает удаленную потоковую процедуру refund() для возврата заказа. Передает серверу идентификатор возвращаемого заказа и сумму возврата. В ответ приходит статус возврата и платежный идентификатор.

Список удаленных процедур

Ниже перечислены gRPC процедуры, используемые в SWiPService:

1 2 3 4 5 6 7 8 9 10 service SWiPService { rpc init (MerchantCredentials) returns (MerchantCredentialsStatus); rpc createOrder (NewOrderData) returns (OrderStatusUpdate); rpc getFrameStream (google.protobuf.Empty) returns (stream Frame); rpc identify(Pincode) returns (Customer); rpc calculateLoyalty(Loyalty) returns (OrderStatusUpdate); rpc pay(PayOrder) returns (PaymentStatusUpdate); rpc closeOrder (OrderAmount) returns (OrderStatusUpdate); rpc refund (OrderAmount) returns (RefundStatusUpdate); }

init

Инициализация настроек мерчанта выполняется путем вызова процедуры init() с настройками в сообщении MerchantCredentials. Процедура init() должна быть проведена перед использованием остальных процедур сервера SWiP SDK. Настройки мерчанта хранятся в оперативной памяти, поэтому вызов процедуры init() требуется выполнять при перезагрузке сервера.

1 rpc init (MerchantCredentials) returns (MerchantCredentialsStatus);

MerchantCredentials

Для передачи настроек от клиента к серверам SWiP (Cash Gateway и STP Gateway) используется сообщение MerchantCredentials:

1 2 3 4 5 6 message MerchantCredentials { string merchantId = 1; string storeId = 2; string cashId = 3; string token = 4; }

 

Параметр

Тип

Описание

Параметр

Тип

Описание

merchantId

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

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

storeId

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

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

cashId

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

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

token

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

Уникальный токен, который предоставляет SWiP.

MerchantCredentialsStatus 

Результат работы от сервера к клиенту возвращается в виде сообщения MerchantCredentialsStatus:

1 2 3 4 message MerchantCredentialsStatus { MerchantCredentialsCode code = 1; // код результата проверки полномочий мерчанта string errorMessage = 2; // детали ошибки, в случае ее возникновения }

Перечисление MerchantCredentialsCode имеет вид:

1 2 3 4 5 enum MerchantCredentialsCode { MERCHANT_CREDENTIALS_EMPTY = 0; MERCHANT_CREDENTIALS_OK = 1; MERCHANT_CREDENTIALS_FAILED = 2; }

Описание значений перечисления MerchantCredentialsCode:

Значение

Описание

Значение

Описание

MERCHANT_CREDENTIALS_EMPTY

Настройки не были переданы.

MERCHANT_CREDENTIALS_OK

Настройки переданы успешно.

MERCHANT_CREDENTIALS_FAILED

Попытка соединения с серверами SWiP не состоялась, детали в поле errorMessage

createOrder

Создание заказа выполняется путем вызова процедуры createOrder.

1 rpc createOrder (NewOrderData) returns (OrderStatusUpdate);

NewOrderData

Для создания заказа используется сообщение NewOrderData, которое содержит данные для формирования заказа со списком покупок.

1 2 3 4 5 6 7 8 9 10 11 message NewOrderData { string sessionCode = 1; string merchantOrderId = 2; string merchantOrderNumber = 3; string merchantCashierId = 4; string merchantCashier = 5; sint64 saleDate = 6; double total = 7; double totalOriginal = 8; repeated Purchase purchases = 9; }

 

1 2 3 4 5 6 7 8 9 10 11 message Purchase { string id = 1; string productId = 2; string name = 3; double quantity = 4; double amount = 5; double price = 6; double discount = 7; double merchantDiscount = 8; string unit = 9; }

 

Параметр

Тип

Описание

Параметр

Тип

Описание

sessionCode

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

Код сессии, генерируемый клиентом Cash Gate, в виде UUID.

merchantOrderId

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

Уникальный идентификатор заказа у мерчанта.

merchantOrderNumber

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

Идентификатор чека у мерчанта.

merchantCashier

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

Имя кассира.

merchantCashierId

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

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

saleDate

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

Время продажи.

total

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

Сумма покупки с учетом скидки.

totalOriginal

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

Сумма без скидки.

purchases

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

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



Purchase

Тип

Описание

Purchase

Тип

Описание

id                                 

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

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

productId 

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

Артикул (идентификатор товара).

name 

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

Название товара.

quantity

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

Количество (штук, килограмм, литров).

amount

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

Стоимость (price * quantity).

price

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

Цена.

discount

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

Сумма скидки.

merchantDiscount

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

Скидка, которую предоставляет мерчант.

unit

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

Единицы измерения.

OrderStatusUpdate

В ответ приходит сообщение OrderStatusUpdate, которое содержит успешно созданный заказ. Далее идентификатор этого заказа используется для его оплаты и закрытия.

1 2 3 4 5 message OrderStatusUpdate { OrderStatusUpdateCode code = 1; // код, характеризующий результат операции Order order = 2; // объект заказа string errorMessage = 3; // детали ошибки }

 

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 message Order { string sessionCode = 1; // код сессии, генерируемый кассой, в виде UUID string shortCode = 2; // альтернатива QR-кода string id = 3; // идентификатор заказа в системе SWiP string customerId = 4; string merchantId = 5; // идентификатор мерчанта string merchantName = 6; // название мерчанта string merchantProfileImageId = 7; // идентификатор изображения в профиле мерчанта string merchantCategory = 8; // категория мерчанта string merchantOrderId = 9; // уникальный идентификатор заказа у мерчанта string merchantOrderNumber = 10; // идентификатор чека у мерчанта string merchantStore = 11; // идентификатор торговой точки string merchantCash = 12; // идентификатор кассы или группы касс string merchantCashierId = 13; // идентификатор кассира string merchantCashier = 14; // имя кассира sint64 saleDate = 15; // дата продажи (в миллисекундах с 01.01.1970) double total = 16; // сумма (с учетом скидки, если таковая есть у клиента) double totalOriginal = 17; // сумма (без учета скидки) double cashback = 18; // размер кэшбэка double discount = 19; // сумма скидки double swipDiscount = 20; // скидка (сумма баллов и дисконта), которую предоставляет SWiP repeated Purchase purchases = 21; // список покупок (товары в чеке) double paid = 22; // сумма, оплаченная клиентом через приложение double unconfirmed = 23; // сумма, оплаченная клиентом через приложение, но не подтвержденная кассой double closeAmount = 24; // сумма, которую касса считает к закрытию заказа int32 availablePoints = 25; // баллы, доступные к списанию string error = 26; // последняя ошибка при оплате заказа double pointsRate = 27; // доля рубля в 1 балле double pointsAsDiscount = 28; // скидка, полученная при списании баллов int32 awardPoints = 29; // начисленные баллы int32 withdrawPoints = 30; // списанные баллы PaymentWay paymentWay = 31; // способ оплаты (APP, STP) OrderStatus orderStatus = 32; // статус заказа (OPEN, CLOSED, LOYALTY_CALCULATION) PaymentMethod paymentMethod = 33; // метод оплаты (CARD, CREDIT, CASH) int32 apiVersion = 34; // версия API string otp = 35; // дополнительный идентификатор заказа (one time paid) string slip = 36; // форматированный текст (80 символов в ширину) с банковской информацией о платеже string rrn = 37; // уникальный идентификатор банковской транзакции string authorizationCode = 38; // авторизационный код платежа string terminalNo = 39; // номер банковского терминала string pan = 40; // маскированный номер карты double merchantDiscount = 41; // скидка, предоставляемая мерчантом string discountCard = 42; // идентификатор дисконтной карты }

 

Перечисление OrderStatusUpdateCode имеет вид:

1 2 3 4 5 enum OrderStatusUpdateCode { ORDER_STATUS_UPDATE_EMPTY = 0; // значение не присвоено ORDER_STATUS_UPDATE_OK = 1; // процедура выполнилась успешно ORDER_STATUS_UPDATE_FAILED = 2; // произошел сбой, детали ошибки в поле errorMessage }

Описание значений перечисления OrderStatusUpdateCode:

Значение

Описание

Значение

Описание

ORDER_STATUS_UPDATE_EMPTY

Значение не присвоено.

ORDER_STATUS_UPDATE_OK

Процедура выполнена успешно.

ORDER_STATUS_UPDATE_FAILED

Произошел сбой, детали ошибки в поле errorMessage.

 

Перечисление PaymentWay имеет вид:

1 2 3 4 5 enum PaymentWay { PAYMENT_WAY_EMPTY = 0; PAYMENT_WAY_APP = 1; PAYMENT_WAY_STP = 2; }

Описание значений перечисления PaymentWay:

Значение

Описание

Значение

Описание

PAYMENT_WAY_EMPTY

Значение не присвоено.

PAYMENT_WAY_APP

Оплата через мобильное приложение.

PAYMENT_WAY_STP

Оплата через Selfie2Pay.

 

Перечисление OrderStatus имеет вид:

1 2 3 4 5 6 enum OrderStatus { ORDER_STATUS_EMPTY = 0; ORDER_STATUS_OPEN = 1; ORDER_STATUS_CLOSED = 2; ORDER_STATUS_LOYALTY_CALCULATION = 3; }

Описание значений перечисления OrderStatus:

Значение

Описание

Значение

Описание

ORDER_STATUS_EMPTY

Значение не присвоено.

ORDER_STATUS_OPEN

Заказ открыт.

ORDER_STATUS_CLOSED

Заказ закрыт.

ORDER_STATUS_LOYALTY_CALCULATION

По заказу проведен расчет внешней лояльности.

 

Перечисление PaymentMethod имеет вид:

1 2 3 4 5 6 enum PaymentMethod { PAYMENT_METHOD_EMPTY = 0; PAYMENT_METHOD_CARD = 1; PAYMENT_METHOD_CREDIT = 2; PAYMENT_METHOD_CASH = 3; }

Описание значений перечисления PaymentMethod:

Значение

Описание

Значение

Описание

PAYMENT_METHOD_EMPTY

Значение не присвоено.

PAYMENT_METHOD_CARD

Оплата картой.

PAYMENT_METHOD_CASH

Оплата наличными.

getFrameStream

Включение камеры, выполнение и сохранение наилучшего снимка совершается путем вызова удаленной потоковой процедуры getFrameStream:

1 rpc getFrameStream (google.protobuf.Empty) returns (stream Frame);

Frame

Клиент принимает от сервера поток кадров в виде сообщения Frame:

1 2 3 4 5 message Frame { bytes frame = 1; // кадры видеопотока с RGB камеры с дорисованной декоративной рамкой DetectionStatus detectionStatus = 2; // статус процесса распознавания string errorMessage = 3; // детали ошибки, в случае ее возникновения }

Перечисление DetectionStatus для передачи статуса процесса распознавания имеет вид:

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 enum DetectionStatus { DETECTION_EMPTY = 0; BESTSHOT_FOUND = 1; DETECTION_FAILED = 2; DETECTION_TIMEOUT = 3; NO_FACE_DETECTED = 4; TOO_MANY_FACES = 5; FACE_IS_NOT_VALID = 6; INCORRECT_HEAD_POSE = 7; LIVENESS_FAILED = 8; FACE_OUTSIDE_BORDERS = 9; SMALL_FACE_SIZE = 10; TOO_BLURRY = 11; HIGH_LEVEL_LIGHTNESS = 12; LOW_LEVEL_LIGHTNESS = 13; LOW_QUALITY = 14; INCORRECT_DEPTH_FRAME = 15; }

Описание значений перечисления DetectionStatus:

Значение

Описание

Значение

Описание

DETECTION_EMPTY

Статус не передан.

BESTSHOT_FOUND

Найден лучший кадр, который подходит для распознавания.

DETECTION_FAILED

Невозможно выполнить распознавание.

DETECTION_TIMEOUT

Время ожидания истекло до завершения процесса поиска лица.

NO_FACE_DETECTED

Нет лица в кадре.

TOO_MANY_FACES

Много лиц в кадре.

FACE_IS_NOT_VALID

Вероятность обнаружения лица в кадре слишком мала.

INCORRECT_HEAD_POSE

Некорректная поза головы.

LIVENESS_FAILED

Проверка на живучесть не пройдена.

FACE_OUTSIDE_BORDERS

Лицо вне области распознавания.

SMALL_FACE_SIZE

Слишком маленькое лицо.

TOO_BLURRY

Изображение слишком размытое для проведения распознавания.

HIGH_LEVEL_LIGHTNESS

Изображение слишком засвеченное для проведения распознавания.

LOW_LEVEL_LIGHTNESS

Изображение слишком затемненное для проведения распознавания.

LOW_QUALITY

Монохромное изображение (в темноте) не подходит для проведения распознавания.

INCORRECT_DEPTH_FRAME

Некорректной снимок глубины.

Если ошибка повторяется, проверьте камеру глубины, возможно, она вышла из строя.

identify

Идентификация покупателя выполняется путем вызова процедуры identify:

1 rpc identify(Pincode) returns (Customer);

Pincode

Для получения идентификатора покупателя сообщение Pincode передается с пустым значением.

1 2 3 message Pincode { string pincode = 1; }

Customer

В ответ приходит сообщение Customer, которое содержит в себе идентификатор покупателя, код возврата.

Идентификатор пользователя SWiP (customerId) является временным. По умолчанию время действия этого идентификатора - 10 минут. После истечения таймаута идентификатор становится недействительным.

1 2 3 4 5 6 7 message Customer { string id = 1; // временный идентификатор пользователя SWiP bool adult = 2; // является ли покупатель совершеннолетним string extId = 3; // внешний идентификатор мерчанта IdentificationCode code = 4; // код возврата string errorMessage = 5; // сообщение об ошибке }

Перечисление IdentificationCode для передачи кода возврата имеет вид:

1 2 3 4 5 6 7 8 9 10 11 enum IdentificationCode { IDENT_EMPTY = 0; IDENT_OK = 1; IDENT_PIN_REQUIRED = 2; IDENT_CUSTOMER_NOT_RECOGNIZED = 3; IDENT_CUSTOMER_NOT_FOUND = 4; IDENT_CUSTOMER_NOT_VALID = 5; IDENT_INCORRECT_PIN = 6; IDENT_PIN_ATTEMPT_EXCEEDED = 7; IDENT_FAILED = 8; }

Описание значений перечисления IdentificationCode:

Значение

Описание

Значение

Описание

IDENT_EMPTY

Значение не присвоено.

IDENT_OK

Пользователь идентифицирован.

IDENT_PIN_REQUIRED

Необходимо ввести ПИН-код.

IDENT_CUSTOMER_NOT_RECOGNIZED

Пользователь не распознан.

IDENT_CUSTOMER_NOT_FOUND

Пользователь не зарегистрирован в системе SWiP.

IDENT_CUSTOMER_NOT_VALID

Пользователь не прошел валидацию (ждет проверки).

IDENT_INCORRECT_PIN

Неверный ПИН-код.

IDENT_PIN_ATTEMPT_EXCEEDED

Количество попыток ввода пин-кода исчерпано.

IDENT_FAILED

Ошибка идентификации.

Если в сообщении Customer пришел код IDENT_PIN_REQUIRED, то необходимо повторно выполнить процедуру identify, а в сообщении Pincode передать значение ПИН-кода.

calculateLoyalty

Только для клиентов, использующих программу лояльности SWiP.

Введение баллов запускается процедурой calculateLoyalty:

1 rpc calculateLoyalty(Loyalty) returns (OrderStatusUpdate);

Loyalty

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

1 2 3 4 5 message Loyalty { string orderId = 1; string customerId = 2; uint32 pointsToWithdraw = 3; }

 

Параметр

Тип

Описание

Параметр

Тип

Описание

orderId

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

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

customerId

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

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

points

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

Баллы, которые ввел пользователь.

OrderStatusUpdate

В ответ приходит сообщение OrderStatusUpdate, которое содержит обновленный заказ. Сообщение OrderStatusUpdate описано в процедуре создания заказа.

pay

Оплата заказа совершается путем вызова процедуры pay:

1 rpc pay(PayOrder) returns (PaymentStatusUpdate);

PayOrder

Если процедура оплаты не была запущена в течение 10 секунд после успешной идентификации, то потребуется ввести ПИН-код при оплате заказа.

Для оплаты заказа используется сообщение PayOrder:

1 2 3 4 5 6 message PayOrder { string orderId = 1; string customerId = 2; double amountToPay = 3; string pincode = 4; }

Параметр

Тип

Описание

Параметр

Тип

Описание

orderId

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

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

customerId

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

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

amountToPay

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

Сумма, которую касса передает для оплаты.

pincode

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

ПИН-код, который необходимо ввести, если процедура оплаты не была запущена в течение 10 секунд.

PaymentStatusUpdate

В ответ приходит сообщение PaymentStatusUpdate, которое содержит успешно оплаченный заказ.

1 2 3 4 5 message PaymentStatusUpdate { PaymentStatusUpdateCode code = 1; // код, характеризующий результат операции Order order = 2; // объект заказа string errorMessage = 3; // детали ошибки }

Перечисление PaymentStatusUpdateCode имеет вид:

1 2 3 4 5 6 7 8 9 enum PaymentStatusUpdateCode { PAYMENT_EMPTY = 0; PAYMENT_OK = 1; PAYMENT_PIN_REQUIRED = 2; PAYMENT_INCORRECT_PIN = 3; PAYMENT_PIN_ATTEMPT_EXCEEDED = 4; PAYMENT_ID_EXPIRED = 5; PAYMENT_FAILED = 6; }

Описание значений перечисления PaymentStatusUpdateCode:

Значение

Описание

Значение

Описание

PAYMENT_EMPTY

Значение не присвоено.

PAYMENT_OK

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

PAYMENT_PIN_REQUIRED

Необходимо ввести ПИН-код.

PAYMENT_INCORRECT_PIN

Введен неверный ПИН-код.

PAYMENT_PIN_ATTEMPT_EXCEEDED

Количество попыток ввода ПИН-кода исчерпано.

PAYMENT_ID_EXPIRED

Срок действия идентификатора пользователя истек (10 минут).

PAYMENT_FAILED

Произошла ошибка.

closeOrder

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

1 rpc closeOrder (OrderAmount) returns (OrderStatusUpdate);

OrderAmount

Для закрытия заказа используется сообщение OrderAmount, которое содержит идентификатор закрываемого заказа и сумму для закрытия.

Для отмены заказа в сумме для закрытия передается значение 0.

1 2 3 4 message OrderAmount { string orderId = 1; double amount = 2; }

 

Параметр

Тип

Описание

Параметр

Тип

Описание

orderId

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

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

amount

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

Сумма, которую касса передает к закрытию.

OrderStatusUpdate

В ответ приходит сообщение OrderStatusUpdate, которое содержит успешно закрытый заказ. Сообщение OrderStatusUpdate описано в процедуре создания заказа.

refund

Возврат заказа выполняется путем вызова процедуры closeOrder.

1 rpc refund (OrderAmount) returns (RefundStatusUpdate);

OrderAmount

Для возврата заказа используется сообщение OrderAmount, которое содержит идентификатор возвращаемого заказа и сумму возврата.

1 2 3 4 message OrderAmount { string orderId = 1; double amount = 2; }

 

Параметр

Тип

Описание

Параметр

Тип

Описание

orderId

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

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

amount

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

Сумма, которую касса передает для возврата.

RefundStatusUpdate

В ответ приходит сообщение RefundStatusUpdate, которое содержит статус возвращенного заказа и платежный идентификатор.

 

1 2 3 4 5 message RefundStatusUpdate { RefundStatus status = 1; // статус возврата string errorMessage = 2; // детали ошибки string slip = 3; // платежный идентификатор (слип) }

Перечисление RefundStatus для передачи статуса возврата имеет вид:

1 2 3 4 5 enum RefundStatus { REFUND_EMPTY = 0; REFUND_SUCCESS = 1; REFUND_FAILED = 2; }

Описание значений перечисления RefundStatus:

Значение

Описание

Значение

Описание

REFUND_EMPTY

Значение не присвоено.

REFUND_SUCCESS

Возврат выполнен успешно.

REFUND_FAILED

Произошла ошибка.