Описание API кассы

Created by Анфиса Полывьян
Last updated: Mar 11, 2020
9 min read

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

Cashbox API - программный интерфейс для работы с онлайн-платежами, выполненными с помощью сервиса SWiP. Позволяет совершать платежи и выполнять их отмену, осуществлять возвраты, получать выписку со всеми заказами, произведенными через платежную систему SWiP.

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

Общее описание процесса оплаты

Процесс оплаты выглядит следующим образом:

  1. Касса отправляет чек в систему SWiP.

  2. Пользователь получает чек в мобильном приложении SWiP и оплачивает.

  3. Касса получает от системы SWiP статус оплаты и закрывает чек. 

Использование QR-кода

Взаимодействие мобильного приложения с кассой или интернет-магазином осуществляется через сервер SWiP.  Чтобы клиент мог получить чек, ему надо знать его идентификатор. В роли идентификатора выступает QR-код.

Возможны 3 варианта использования QR-кода:

QR-код с идентификатором кассы

В этом случае клиент запрашивает чек по идентификатору кассы. Такой подход возможен только в случае, если касса работает в режиме одного активного ордера. Сам QR-код может быть напечатан один раз и он не меняется, если идентификатор кассы не был изменен (помещается непосредственно на кассе).

Место применения:

  • оффлайн-магазин;

  • фастфуд;

  • кофейня.

QR-код с идентификатором ордера

Для каждого заказа создается свой QR-код. Он может либо печататься каждый раз, либо отображаться на мониторе.

Место применения:

  • ресторан (печатается на пречеке);

  • онлайн-магазин (показывается на странице оплаты);

  • оффлайн-магазин (показывается на экране кассы или монитора).

QR-код с идентификатором клиента

Пользователь показывает QR-код на телефоне, касса с помощью 2D-сканера сканирует и отправляет его на сервер. Клиент отправляет запрос на сервер по своему идентификатору.

Место применения:

  • магазин, оборудованный 2D-сканером.

Схема взаимодействия



В предложенной схеме клиент сканирует QR (QR-код с идентификатором кассы или QR-код с идентификатором ордера). Схема для QR-кода с идентификатором клиента будет отличаться лишь тем, что readQR() будет выполнять касса.

Режимы работы кассы

Касса может работать в двух режимах: последовательный и параллельный. 

  • Последовательный режим. Активным является только один ордер. Нельзя создавать новый ордер пока предыдущий не будет оплачен или отменен. С таким режимом работают кассы в оффлайн-магазине или фастфуде, где оплата производится перед получением товара/покупки.

  • Параллельный режим. Может быть много открытых ордеров. В этом режиме работают кассы в ресторане, интернет-магазине. 

С точки зрения сервиса SWiP различие только в типе QR-кода. Со стороны кассы различие более существенное. Ниже представлены сценарии, подробно описывающие поведение системы.

Сценарии использования

Параметры, указанные в синих квадратных скобках, конфигурируются администратором в настройках плагина SWiP для кассы.

Оплата в оффлайн-магазине/фастфуде: QR-код

Действующие лица

Пользователь, Кассир, Касса

Описание

Оплата покупки в оффлайн-магазине с использованием платежной системы SWiP.

Триггер

Пользователь сообщает кассиру, что хочет произвести оплату через сервис SWiP.

Предусловия

Касса работает в режиме одного активного ордера [ single.order=true ]

Цели

Пользователь: оплатить покупку платежной системой SWiP.
Кассир: рассчитать покупателя.
Касса: провести оплату.

Успешный сценарий:

  1. Кассир выбирает способ оплаты SWiP.

  2. Касса создает заказ в системе SWiP.
    В ордере в поле sessionCode записывает текстовое значение QR-кода.

    Варианты QR-кода:

    1. Статический QR-код (наклейка на кассе). Пример: https://swip.one/?qr=12345  [ identity = CASHBOX ]

    2. QR-код показывается на экране кассы или на мониторе [ identity = ORDER ]

    3. Касса сканирует QR-код с телефона пользователя с помощью 2D-сканера [ identity = CUSTOMER ]

     

  3. Касса отображает модальное окно с ожиданием и в цикле запрашивает текущий статус заказа.

  4. В это время пользователь сканирует QR-код, и мобильное приложение запрашивает чек. 
    4.1 Сервер сопоставляет клиента и мерчанта, проверяет есть ли скидка в виде cashback на этого клиента и какая ставка.

  5. Пользователь получает электронный пречек для оплаты на экран мобильного приложения и подтверждает оплату.
    Информация в пречеке:

    • Товары (наименования товара, количество товара, сумма, скидка, сумма чека);

    • ФИО кассира и номер пречека;

    • 4 последние цифры карты, с которой будет произведена оплата.


  6. Деньги списываются с карты пользователя, привязанной к приложению.

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

  8. Кассир отдает чек пользователю.

  9. Пользователь видит в мобильном приложении SWiP подтверждение оплаты, оценивает предоставленный сервис по пятибалльной шкале.
    После оплаты банк-эмитент отправляет пользователю СМС-уведомление с суммой списанных средств.


Результат

Пользователь успешно оплатил покупку платежной системой SWiP.

Расширения:

3a

Кассир отменяет ордер.
Результат: Вызывается сценарий "Отмена заказа".

3b

Касса отменяет ордер по тайм-ауту (30 секунд).
Результат: Сбрасывание ордера. Статус заказа меняется на CLOSED.
Переход к шагу 1.

4a

Пользователь показывает QR-код на телефоне, в этот момент он ожидает чек с сервера.

Результат: Переход к шагу 5.

6a

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

Результат: Вызывается сценарий "Отмена заказа".
Пользователь оплачивает банковской картой или наличными.

7a

Касса в течение установленного тайм-аута не подтвердила проведение оплаты.

Результат: Происходит возврат на оплату. Возвращаются параметры со статусом OPEN.
Переход на шаг 5.

7b

Касса в течение установленного тайм-аута не вызвала метод закрытия заказа. 

Результат: Оплата не проходит, возвращаются параметры со статусом CLOSED. Переход на шаг 1.

7c

Касса не вызвала метод закрытия заказа.

Результат: Следующий заказ закрывает предыдущий. Заказ не оплачен, возвращаются параметры со статусом CLOSED.
Переход на шаг 1.

Оплата в оффлайн-магазине/фастфуде: SELFIETOPAY

Действующие лица

Пользователь, Кассир, Касса

Описание

Оплата покупки в оффлайн-магазине с использованием платежной системы SWiP.

Триггер

Пользователь сообщает, что будет оплачивать приложением SWiP путем STP.

Предусловия 

Касса работает в режиме одного активного ордера [ single.order=true ]

Цели

Пользователь: оплатить покупку платежной системой SWiP.
Кассир: рассчитать покупателя.
Касса: осуществить оплату.

Успешный сценарий:

  1. Кассир выбирает способ оплаты SWiP.

  2. Касса создает заказ в системе SWiP. После успешного создания заказа вызывает метод включения камеры.

  3. Ожидание оплаты происходит до тех пор пока пользователь не посмотрит в камеру и система его не распознает. Касса показывает модальное окно с ожиданием.
    3.1 Сервер сопоставляет клиента и мерчанта, проверяет есть ли скидка в виде cashback на этого клиента и какая ставка.

  4. Деньги списываются с карты пользователя, привязанной к приложению.

  5. Касса печатает фискальный чек, в цикле запрашивает статус платежа, получает подтверждение об оплате чека и вызывает метод закрытия заказа.

  6. Кассир отдает чек пользователю.

  7. Касса вызывает метод закрытия камеры.

Результат

Пользователь успешно оплатил покупку платежной системой SWiP.

Расширения:

3a

Кассир отменяет заказ.
Результат: Вызывается сценарий "Отмена заказа".

3b

Касса выходит по тайм-ауту (время ожидания камеры максимум 10 секунд)
Результат: Сбрасывание ордера.
Переход на шаг 1.

4a

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

Результат: Вызывается сценарий "Отмена заказа".
Пользователь оплачивает банковской картой или наличными.

5a

Касса в течение установленного тайм-аута не подтвердила проведение оплаты.

Результат: Происходит возврат на оплату. Возвращаются параметры со статусом OPEN.
Переход на шаг 3.

5b

Касса в течение установленного тайм-аута не вызвала метод закрытия заказа. 

Результат: Оплата не проходит, возвращаются параметры со статусом CLOSED. Переход на шаг 1.

5c

Касса не вызвала метод закрытия заказа.

Результат: Следующий заказ закрывает предыдущий. Заказ не оплачен, возвращаются параметры со статусом CLOSED.
Переход на шаг 1.

Оплата в ресторане

Действующие лица

Пользователь, Официант, Касса

Описание 

Оплата счета в ресторане с использованием платежной системы SWiP.

Триггер

Пользователь сообщает, что хочет оплатить счет.

Предусловия

Касса работает в режиме нескольких активных ордеров [ single.order = false ]

Цели

Пользователь: оплатить счет платежной системой SWiP.
Официант: рассчитать покупателя.
Касса: провести оплату.

Успешный сценарий:

  1. Официант нажимает на кассе "Пречек" (по умолчанию QR-код SWiP печатается на всех пречеках установленных касс).

  2. Касса создает заказ в системе SWiP. 

  3. После получения объекта заказа касса печатает пречек с QR-кодом SWiP из заказа.

  4. Официант относит пречек пользователю и спрашивает каким образом он будет оплачивать.

  5. Пользователь сообщает, что будет оплачивать сервисом SWiP.

  6. Пользователь сканирует QR-код, и мобильное приложение запрашивает чек.
    6.1 Сервер сопоставляет клиента и мерчанта, проверяет есть ли скидка в виде cashback на этого клиента и какая ставка.

  7. Пользователь получает электронный пречек для оплаты на экран мобильного приложения и подтверждает оплату.
    Информация в пречеке:

    • Товары (наименования товара, количество товара, сумма, скидка, сумма чека);

    • ФИО официанта и номер пречека;

    • 4 последние цифры карты, с которой будет произведена оплата.


  8. Деньги списываются с карты пользователя, привязанной к приложению.

  9. Касса печатает фискальный чек, в цикле запрашивает статус платежа, получает подтверждение об оплате чека и вызывает метод закрытия заказа. 

  10. Пользователь видит в мобильном приложении SWiP подтверждение оплаты, оценивает предоставленный сервис по пятибалльной шкале.
    После оплаты банк-эмитент отправляет пользователю СМС-уведомление с суммой списанных средств.

Результат

Пользователь успешно оплатил счет платежной системой SWiP.

Расширения:

5a

Пользователь решает заказать дополнительные блюда.

Результат: Официант вызывает отмену пречека. 

7a

Пользователь решает заказать дополнительные блюда после того, как нажал кнопку "Оплатить" в мобильном приложении.

Результат: Печатается второй пречек.

7b

Пользователь решает заказать дополнительные блюда после того, как нажал кнопку "Оплатить" в мобильном приложении.

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

7c

Пользователь решает заказать дополнительные блюда после того, как нажал кнопку "Оплатить" в мобильном приложении.

Результат: Касса добавляет тип оплаты SWiP с уже оплаченной суммой, официант предлагает пользователю доплатить любым типом оплаты (банковская карта, наличный расчет).

8a

Пользователь не может оплатить (нет денег, недоступен банк, нет интернет-соединения), официант нажимает "Отмена" или касса выходит по тайм-ауту. 

Результат: Вызывается сценарий "Отмена заказа".
Пользователь оплачивает банковской картой или наличными.

9a

Касса в течение установленного тайм-аута не подтвердила проведение оплаты.

Результат: Происходит возврат на оплату. Возвращаются параметры со статусом OPEN.
Переход на шаг 7.

9b

Касса в течение установленного тайм-аута не вызвала метод закрытия заказа. 
Результат: Оплата не проходит, возвращаются параметры со статусом CLOSED. Переход на шаг 1.

9c

Касса не вызвала метод закрытия заказа.

Результат: Следующий заказ закрывает предыдущий. Заказ не оплачен, возвращаются параметры со статусом CLOSED.
Переход на шаг 1.

Оплата в интернет-магазине (ПК)

Действующие лица

Пользователь, Система

Описание

Оплата покупки в онлайн-магазине с использованием платежной системы SWiP.

Триггер

Пользователь выбирает способ оплаты SWiP.

Предусловия

Заходит на сайт магазина с ПК.

Цели

Пользователь: оплатить покупку платежной системой SWiP.
Система: провести оплату.

Успешный сценарий:

  1. Интернет-магазин создает заказ в системе SWiP.
    В ордере в поле sessionCode записывает текстовое значение QR-кода.

  2. После получения ордера интернет-магазин показывает QR-код на странице оплаты.

  3. Пользователь сканирует с помощью мобильного приложения SWiP QR-код, и мобильное приложение запрашивает чек.

  4. Пользователь получает пречек для оплаты на мобильный телефон и подтверждает оплату.

  5. Деньги списываются с карты пользователя, привязанной к приложению.

  6. Приложение отображает, что оплата прошла успешно. После оплаты банк-эмитент отправляет пользователю СМС-уведомление с суммой списанных средств.

  7. В случае удачной оплаты интернет-магазин получает заказ со статусом CLOSED.

  8. На странице интернет-магазина отображается, что заказ оплачен.

Результат

Пользователь успешно оплатил покупку платежной системой SWiP.

Расширения:

5a

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

Результат: Вызывается сценарий "Отмена заказа".
Пользователь оплачивает банковской картой.

Оплата в интернет-магазине (смартфон)

Действующие лица

Пользователь, Система

Описание

Оплата покупки в онлайн-магазине с использованием платежной системы SWiP.

Триггер

Пользователь выбирает способ оплаты SWiP.

Предусловия

Заходит на сайт магазина со смартфона.

Цели

Пользователь: оплатить счет платежной системой SWiP.
Система: провести оплату.

Успешный сценарий:

  1. Интернет-магазин создает заказ в SWiP. 
    В ордере в поле sessionCode записывает текстовое значение QR-кода.

  2. После получения ордера интернет-магазин показывает QR-код на странице оплаты.

  3. Пользователь нажимает на сайте интернет-магазина кнопку SWiP и переходит в мобильное приложение SWiP после введения пароля.

  4. Пользователь получает пречек для оплаты на смартфон и нажимает оплатить.

  5. Деньги списываются с карты пользователя, привязанной к приложению.

  6. Приложение отображает, что оплата прошла успешно. После оплаты банк-эмитент отправляет пользователю СМС-уведомление с суммой списанных средств.

  7. В случае удачной оплаты интернет-магазин получает заказ со статусом CLOSED.

  8. Пользователь возвращается на сайт интернет-магазина.

  9. На странице интернет-магазина отображается, что заказ оплачен.

Результат

Пользователь успешно оплатил покупку платежной системой SWiP.

Расширения:

3a

Пользователь делает снимок экрана с QR-кодом на смартфоне, выходит из браузера, открывает мобильное приложение SWiP, загружает картинку с QR-кодом из галереи, приложение считывает код.

Результат: Переход к шагу 4.

5a

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

Результат: Вызывается сценарий "Отмена заказа".
Пользователь оплачивает банковской картой.

Отмена заказа

Действующие лица

Касса

Описание

Отмена заказа до оплаты пользователем.

Триггер

Завершился тайм-аут или кассир нажал кнопку "Отмена".

Предусловия

Заказ/покупка еще не оплачен.

Цели

Отменить заказ.

Успешный сценарий:

  1. Касса запрашивает отмену заказа.

  2. Статус заказа меняется на CLOSED.

Возврат денег

Действующие лица

Пользователь, Кассир, Касса

Описание

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

Триггер

Пользователь сообщает, что хочет вернуть деньги за товар.

Предусловия

Заказ/покупка оплачен.

Цели

Вернуть деньги пользователю по чеку.

Успешный сценарий:

  1. Кассир производит на кассе возврат.

  2. Касса отправляет запрос на возврат, в параметрах передается полная сумма возврата по чеку и уникальный идентификатор этого платежа в системе мерчанта.
    Создание возврата возможно только для платежей в статусе CLOSED.

Результат

Деньги возвращены пользователю.

Расширения:

2a

Сумма возврата меньше суммы чека.

Результат: В параметрах передается часть суммы чека. Осуществляется частичный возврат.
Можно делать несколько частичных возвратов, сумма всех возвратов не должна превышать сумму чека.

Получить все заказы

Действующие лица

Касса

Описание

Получение списка со всеми заказами за день.

Триггер

В кассе произошел сбой.

Предусловия



Цели

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

Сценарий:

1. Касса запрашивает список заказов за необходимый день.

Результат

Касса: успешно получила выписку со всеми заказами.

Обработка исключительных сценариев

Действующие лица

Пользователь, Касса

Описание

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

Триггер

Выключение света/интернета после отправки заказа кассой.

Цели

Произвести возврат денежных средств пользователю.

Сценарий:

  1. У пользователя в приложении показывается, что деньги списаны.

  2. Система SWiP ожидает подтверждения от кассы в отношении смогла ли она успешно получить заказ в состоянии CLOSED (оплачено).

  3. Касса не получила заказ в течении определенного времени - происходит возврат денег пользователю и отмена заказа.

  4. На кассе будет показано следующее сообщение: "Оплата не прошла. Предложите клиенту оплату наличными".

  5. В приложении пользователю будет показано, что сервис SWiP произвел возврат денег.

  6. Пользователь оплачивает на кассе наличными.