API кассы

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

Касса - ПО у мерчанта.

Мерчант - предприятие, поставщик товаров и/или услуг, подключающее себе сервис оплаты SWiP. 

Интегратор - сотрудник кассы/мерчанта/сторонний, который осуществляет соединение кассы мерчанта с системой SWiP и дальнейшую поддержку.

Биометрический терминал Selfie2Pay - устройство, через которое совершается бесконтактная оплата по биометрии лица.

Внешняя лояльность - программа лояльности, которую предоставляет мерчант/касса.

Двухстадийная оплата - операция по оплате, которая требует дополнительного подтверждения.

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

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

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

Адреса интеграции

Адрес интеграционной среды https://capi-test.smartwallet.ru.

Адрес продакшн среды https://capi3.smartwallet.ru.

Идентификация заказа и сессии

Идентификаторами заказа являются поля id и merchantOrderId.          

Название поля

Описание

Название поля

Описание

id (UUID)

Идентификатор в системе SWiP. Касса не должна его ставить. Касса создает заказ, посылая объект заказа (Order). Обратно приходит так же объект Order c установленным полем id. Дальше это поле используется в запросах GET.

merchantOrderId

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

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

Название поля

Описание

Название поля

Описание

sessionCode

Идентификатор сессии (текстовое значение зашифрованное в QR-коде). Если касса работает в режиме ресторана, то QR-код берется из ответа сервера на запрос создания заказа.

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

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

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

Аутентификация осуществляется по статическому токену, который надо передавать в заголовке HTTP-запросов.

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

Название поля

Пример значения

Описание

Название поля

Пример значения

Описание

Authorization

Bearer 8c6b8b64-6815-6084-0a3e-178401251b68

Токен передает сотрудник SWiP после подключения мерчанта.

X-Merchant-ID

ABCD

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

X-Store-ID

Shipilovo

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

 

X-Cash-ID

1231

Номер кассы в системе мерчанта.

На стороне SWiP идентификатор не проверяется и не регистрируется. В дальнейшем используется для статистики по торговым точкам.

Api-Version*

3

Версия API.

* Данный документ действителен для версии API 2 и выше.

 

Коды ответа

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

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

Если возвращается HTTP-код 200, запрос выполнен успешно. Если HTTP-код 4xx или 5хх, значит произошла ошибка и вернется следующий объект:

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

Сценарии интеграции

Есть несколько сценариев интеграции Cashbox API. Они зависят от способа оплаты и настроек магазина.

Сеть розничных магазинов, фастфуд

Пример реализации:

  1. Пользователь делает заказ на кассе.

  2. Касса создает заказ, передает в заголовках API запросов параметры (подробнее в главе Аутентификация):
    X-Merchant-ID - идентификатор мерчанта;
    X-Store-ID - идентификатор торговой точки в системе мерчанта;
    X-Cash-ID - номер кассы в системе мерчанта.

  3. Пользователь подтверждает оплату.

  4. Касса закрывает заказ и печатает фискальный чек.

Вендинговый аппарат

Пример реализации:

  1. Пользователь выбирает товар на вендинговом аппарате.

  2. Вендинговый аппарат создает заказ, передает в заголовках API запросов параметры (подробнее в главе Аутентификация):
    X-Merchant-ID - идентификатор мерчанта;
    X-Store-ID - идентификатор торгового аппарата;
    X-Cash-ID - IMEI модема или пустое значение.

  3. Пользователь подтверждает оплату и получает товар.

Касса самообслуживания

Если оплата осуществляется по QR-коду, то пример реализации, как у сети розничных магазинов, фастфудов.

Если оплата осуществляется по биометрии лица на встроенной камере RealSense, то дополнительно необходимо использовать SDK.

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

Для кассы нет разницы каким образом будет оплачен заказ - через биометрический терминал Selfie2Pay или с помощью QR-кода.

QR-код

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

Selfie2Pay

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

Объект заказа (Order)

Объект заказа (Order) содержит всю информацию о заказе, актуальную на текущий момент времени. Он формируется при создании заказа и приходит в ответ на некоторые запросы.

В объекте заказа могут приходить другие поля, которые касса сейчас не использует. Их необходимо игнорировать.

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

UUID

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

merchantOrderId*

string

Идентификатор заказа в системе мерчанта.
(Если мерчант для идентификации заказов использует формат UUID, то это значение может быть использовано для идентификатора заказа в системе SWiP).

apiVersion

integer

Версия API, по которой оплачен заказ.

authorizationCode

string

Авторизационный код платежа.

cashback

double

Сумма кэшбэка.

closeAmount*

double

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

customerId

string

Идентификатор клиента оплатившего заказ. Значение присутствует после закрытия заказа.

discountCard

string

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

error

string

Текстовое описание последней ошибки при оплате заказа.

merchantCash

string

Номер кассы или группы касс на стороне мерчанта (ставить не нужно, берется из заголовков HTTP-запроса).

merchantCashier*

string

Имя кассира.

merchantCashierId*

string

Идентификатор кассира. Применимо к кассам, которые проставляют этот параметр.

merchantCategory

string

Описание сферы деятельности мерчанта.

merchantCommission

double

Внешняя комиссия мерчанта.

merchantDiscount

double

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

merchantId

string

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

merchantName

string

Название мерчанта.

merchantOrderNumber*

string

Номер заказа в системе мерчанта (обычно печатается в чеке).

merchantProfileImageId

string

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

merchantStore

string

Идентификатор торговой точки (ставить не нужно, берется из заголовков HTTP-запроса).

orderNumber

string

Номер заказа в банке-эквайере.

orderStatus

OrderStatus

Статус заказа. Возможные значения: OPEN, CLOSED, LOYALTY_CALCULATION.

paid

double

Сумма, оплаченная клиентом через приложение. Значение присутствует после подтверждения оплаты банком.

pan

string

Маскированый номер карты.

paymentMethod

PaymentMethod

Способ оплаты. Возможные значения: CARD, CREDIT, CASH.

paymentSystem

PaymentSystem

Платежная система. Возможные значения: MIR, AMEX, VISA, MASTERCARD, MAESTRO.

purchases

object

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

refunded

double

Сумма возврата по заказу.

rrn

string

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

saleDate*

long

Время продажи в системе мерчанта (в миллисекундах с 01.01.1970). Совпадение даты создания и даты, которая будет напечатана на чеке не обязательно.

sessionCode*

string

QR-код.
Если поле будет отправлено пустым, то сервер SWiP сгенерирует его значение.
В случае оплаты через Selfie2Pay это поле заполнять не надо.

slip

string

Форматированный текст (80 символов в ширину) с банковской информацией о платеже.

swipDiscount

double

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

terminalNo

string

Номер банковского терминала.

total*

double

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

totalOriginal*

double

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

unconfirmed

double

Сумма, оплаченная клиентом через приложение, но не подтвержденная кассой (paid>=unconfirmed).

Объект Purchases

Параметр

Тип

Описание

Параметр

Тип

Описание

id

UUID

Идентификатор товара.
Если мерчант для идентификации товаров использует UUID, то он может быть использован в качестве id. Если нет, то сервер SWiP генерирует UUID.                                   

productId

string

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

name

string 

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

quantity

double

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

merchantDiscount

double

Скидка, предоставляемая мерчантом.
Поле заполняется после обновления заказа, если был получен статус заказа LOYALTY_CALCULATION.

price 

double

Цена.

amount

double

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

unit

Unit

Единицы измерения (LITERS, KILOGRAMS, PIECES).

Пример объекта ORDER

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 { "apiVersion": 3, "authorizationCode": "string", "cashback": 0.0, "closeAmount": 0.0, "customerId": null, "discountCard": "string", "error": "string", "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantCash": "88", "merchantCashier": "Маслова Вера", "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144", "merchantCategory": "Электроника", "merchantCommission": 0, "merchantDiscount": 0, "merchantId": "VZLT", "merchantName": "shop", "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantOrderNumber": "11", "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381", "merchantStore": "3", "orderNumber": "28048058915136358726242016980679", "orderStatus": "OPEN", "paid": 0.0, "pan": "string", "paymentMethod": "CARD", "paymentSystem": "MIR", "purchases": [ { "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78", "merchantDiscount": 0, "name": "Sprite 0,33 л", "productId": null, "quantity": 0, "unit": "string", "price": 50.0, "amount": 50.0, } ], "refunded": 0, "rrn": "string", "saleDate": 1540485815026, "sessionCode": "https://swip.one/?qr=6794742", "slip": "...very long text...", "swipDiscount": 0, "terminalNo": "string", "total": 50.0, "totalOriginal": 50.0, "unconfirmed": 0.0 }

Создать заказ

Чтобы отправить заказ на оплату, необходимо создать объект заказа - Order. Он содержит всю необходимую информацию для проведения оплаты.
Если в этом есть необходимость, в объекте Purchases можно передавать всегда один товар, к примеру какую-то услугу или сервис.

Для касс, которые работают в режиме фастфуда или розничной торговли, заказ может находиться в статусе OPEN 10 минут. Для касс, работающих в режиме ресторана, - 10 часов.

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

1 POST /orders

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

Параметр

Тип

Описание

Параметр

Тип

Описание

sessionCode

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

Текстовое значение QR-кода.
Касса может присылать какое-либо значение в этом поле. Если поле будет отправлено пустым, то сервер SWiP сгенерирует его значение.
В случае оплаты через Selfie2Pay это поле заполнять не надо.

merchantOrderId

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

Уникальный идентификатор заказа у мерчанта.
(Если мерчант для идентификации заказов использует формат UUID, то это значение может быть использовано для идентификатора заказа в системе SWiP).

merchantOrderNumber

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

Номер заказа в системе мерчанта (обычно печатается в чеке).

merchantCashier

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

Имя кассира.

merchantCashierId

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

Идентификатор кассира. Применимо к кассам, которые проставляют этот параметр.

saleDate

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

Время продажи в системе мерчанта (в миллисекундах с 01.01.1970). Совпадение даты создания и даты, которая будет напечатана на чеке не обязательно.

total

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

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

totalOriginal

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

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

purchases

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

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

id

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

Идентификатор товара.
Если мерчант для идентификации товаров использует UUID, то он может быть использован в качестве id. Если нет, то сервер SWiP генерирует UUID.                                   

productId

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

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

name

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

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

quantity

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

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

merchantDiscount

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

Скидка, предоставляемая мерчантом.
Поле заполняется после обновления заказа, если был получен статус заказа LOYALTY_CALCULATION.

price 

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

Цена.

amount

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

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

unit

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

Единицы измерения (LITERS, KILOGRAMS, PIECES).

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 { "guests": 0, // количество гостей "merchantCashier": "Маслова Вера", // имя кассира "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144", // идентификатор кассира "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1", // уникальный идентификатор заказа у мерчанта "merchantOrderNumber": "11", // номер заказа в системе мерчанта (обычно печатается в чеке) "purchases": [ { "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78", // идентификатор товара "merchantDiscount": 0, // скидка, предоставляемая мерчантом "name": "Sprite 0,33 л", // наименование товара "productId": null, // артикул товара в системе мерчанта "quantity": 0, // количество (в выбранных единицах измерения) "unit": "string", // единицы измерения (LITERS, KILOGRAMS, PIECES) "price": 50.0, // цена товара "amount": 50.0, // общая сумма (цена * количество) } ], "saleDate": 1540485815026, // время продажи в системе мерчанта (в миллисекундах с 01.01.1970) "sessionCode": "https://swip.one/?qr=6794742", // текстовое значение QR-кода "total": 50.0, // сумма с учетом скидки "totalOriginal": 50.0 // сумма без учета скидки }

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

В ответ на запрос придет тот же заказ с проставленными полями: id - SWiP orderId, sessionCode.

Если sessionCode был отправлен пустым, то обратно вернется заполненное поле, его надо напечатать в пречеке или показать на экране (кассовом) покупателю.

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

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 { "apiVersion": 3, // версия API "authorizationCode": "string", // авторизационный код платежа "cashback": 0.0, // размер кэшбэка "closeAmount": 0.0, "customerId": null, "discountCard": "string", // номер дисконтной карты клиента "error": "string", // последняя ошибка при оплате заказа "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1", // идентификатор заказа в системе SWiP "merchantCash": "88", // идентификатор кассы или группы касс "merchantCashier": "Маслова Вера", // имя кассира "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144", // идентификатор кассира "merchantCategory": "Электроника", // категория мерчанта "merchantCommission": 0, // внешняя комиссия мерчанта "merchantDiscount": 0, // скидка, предоставляемая мерчантом "merchantId": "VZLT", // идентификатор мерчанта "merchantName": "shop", // название мерчанта "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1", // уникальный идентификатор заказа у мерчанта "merchantOrderNumber": "11", // номер заказа в системе мерчанта (обычно печатается в чеке) "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381", // идентификатор изображения в профиле мерчанта "merchantStore": "3", // идентификатор торговой точки "orderNumber": "28048058915136358726242016980679", // номер заказа "orderStatus": "OPEN", // статус заказа "paid": 0.0, "pan": "string", // маскированный номер карты "paymentMethod": "CARD", // способ оплаты "paymentSystem": "MIR", // платежная система "purchases": [ // список покупок (товары в чеке) { "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78", // идентификатор товара в системе SWiP "merchantDiscount": 0, // скидка, предоставляемая мерчантом "name": "Sprite 0,33 л", // наименование товара "productId": null, // идентификатор товара в системе мерчанта "quantity": 0, // количество (в выбранных единицах измерения) "unit": "string", // единицы измерения (LITERS, KILOGRAMS, PIECES) "price": 50.0, // цена товара "amount": 50.0, // общая сумма (цена * количество) } ], "refunded": 0, "rrn": "string", // уникальный идентификатор банковской транзакции "saleDate": 1540485815026, // время продажи в системе мерчанта (в миллисекундах с 01.01.1970) "sessionCode": "https://swip.one/?qr=6794742", // текстовое значение QR-кода "slip": "...very long text...", // форматированный текст с банковской информацией о платеже "swipDiscount": 0, // скидка (сумма баллов и дисконта), которую предоставляет SWiP "terminalNo": "string", // номер банковского терминала "total": 50.0, // сумма (с учетом скидки, если таковая есть у клиента) "totalOriginal": 50.0, // сумма (без учета скидки) "unconfirmed": 0.0 // сумма, оплаченная клиентом через приложение, но не подтвержденная кассой }

Создать заказ (1С)

Чтобы отправить заказ на оплату, необходимо создать объект заказа - Order. Он содержит всю необходимую информацию для проведения оплаты.

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

1 POST /1с-orders

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

Параметр

Тип

Описание

Формат

Параметр

Тип

Описание

Формат

sessionCode

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

Текстовое значение QR-кода.

Строка длиной от 1 до 100 символов.

merchantOrderId

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

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

Формат UUID.

merchantOrderNumber

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

Номер заказа в системе мерчанта.

Наличие только цифр.

merchantCashier

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

Имя кассира.

Строка длиной от 0 до 50 символов.

merchantCashierId

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

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

Строка длиной от 0 до 50 символов.

saleDate

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

Время продажи в системе мерчанта (в миллисекундах с 01.01.1970).

Ненулевое значение.

total

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

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

Ненулевое значение.

totalOriginal

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

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

Ненулевое значение.

purchases

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

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

Ненулевое значение, в списке должен быть минимум 1 объект.

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 { "id": "string", "merchantCashier": "string", // имя кассира "merchantCashierId": "string", // идентификатор кассира "merchantOrderId": "string", // уникальный идентификатор заказа у мерчанта "merchantOrderNumber": "string", // номер заказа в системе мерчанта (обычно печатается в чеке) "purchases": [ { "amount": 0, "discount": 0, "id": "string", "merchantDiscount": 0, "name": "string", "price": 0, "productId": "string", "quantity": 0, "unit": "string", } ], "saleDate": "2019-07-16T08:09:42.276Z", // время продажи в системе мерчанта (в миллисекундах с 01.01.1970) "sessionCode": "string", // текстовое значение QR-кода "total": 0, // сумма с учетом скидки "totalOriginal": 0 // сумма без скидки }

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

В ответ на запрос придет тот же заказ с проставленными полями: id - SWiP orderId, sessionCode. Если sessionCode был отправлен пустым, то обратно вернется заполненное поле, его надо напечатать в пречеке или показать на экране (кассовом) покупателю.

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

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 { "apiVersion": 3, "authorizationCode": "string", "cashback": 0.0, "closeAmount": 0.0, "customerId": null, "discountCard": "string", "error": "string", "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantCash": "88", "merchantCashier": "Маслова Вера", "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144", "merchantCategory": "Электроника", "merchantCommission": 0, "merchantDiscount": 0, "merchantId": "VZLT", "merchantName": "shop", "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantOrderNumber": "11", "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381", "merchantStore": "3", "orderNumber": "28048058915136358726242016980679", "orderStatus": "OPEN", "paid": 0.0, "pan": "string", "paymentMethod": "CARD", "paymentSystem": "MIR", "purchases": [ { "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78", "merchantDiscount": 0, "name": "Sprite 0,33 л", "productId": null, "quantity": 0, "unit": "string", "price": 50.0, "amount": 50.0, } ], "refunded": 0, "rrn": "string", "saleDate": 1540485815026, "sessionCode": "https://swip.one/?qr=6794742", "slip": "...very long text...", "swipDiscount": 0, "terminalNo": "string", "total": 50.0, "totalOriginal": 50.0, "unconfirmed": 0.0 }

Получить заказ

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

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

1 GET /orders/{id}

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

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

Уникальный идентификатор заказа в системе SWiP.

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

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

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

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 { "apiVersion": 3, "authorizationCode": "string", "cashback": 0.0, "closeAmount": 0.0, "customerId": null, "discountCard": "string", "error": "string", "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantCash": "88", "merchantCashier": "Маслова Вера", "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144", "merchantCategory": "Электроника", "merchantCommission": 0, "merchantDiscount": 0, "merchantId": "VZLT", "merchantName": "shop", "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantOrderNumber": "11", "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381", "merchantStore": "3", "orderNumber": "28048058915136358726242016980679", "orderStatus": "OPEN", "paid": 0.0, "pan": "string", "paymentMethod": "CARD", "paymentSystem": "MIR", "purchases": [ { "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78", "merchantDiscount": 0, "name": "Sprite 0,33 л", "productId": null, "quantity": 0, "unit": "string", "price": 50.0, "amount": 50.0, } ], "refunded": 0, "rrn": "string", "saleDate": 1540485815026, "sessionCode": "https://swip.one/?qr=6794742", "slip": "...very long text...", "swipDiscount": 0, "terminalNo": "string", "total": 50.0, "totalOriginal": 50.0, "unconfirmed": 0.0 }

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

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

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

1 GET /orders/{id}/status

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

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

Уникальный идентификатор заказа в системе SWiP.

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

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

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

1 2 3 4 5 6 7 8 { "totalOriginal":210.0, "total":210.0, "paid":0.0, "unconfirmed":0.0, "refunded":0.0, "status":"CLOSED" }

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

Значение

Описание

Значение

Описание

OPEN

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

CLOSED

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

LOYALTY_CALCULATION

По заказу проведен расчёт внешней лояльности. Необходимо выполнить обновление заказа.

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

Касса ожидает проведения оплаты 45 секунд. Если за это время не произойдет оплата, касса закрывает заказ с amount=0.

Заказ может иметь следующие статусы: OPEN, CLOSED, LOYALTY_CALCULATION.

Оплата определяется по полю paid. Допустим, что проводится оплата на 100 рублей:

  1. Создание заказа:
    status=OPEN, totalOriginal=100, total=100, paid=0, unconfirmed=0

  2. Проведение оплаты:
    status=OPEN, totalOriginal=100, total=100, paid=100, unconfirmed=100

  3. Закрытие заказа:
    status=CLOSED, totalOriginal=100, total=100, paid=100, unconfirmed=0

Если закрыть заказ с amount=0, то происходит отмена оплаты:
status=CLOSED, totalOriginal=100, total=100, paid=0, unconfirmed=0

Обновить заказа

Данный метод используется только, если поле status имеет значение LOYALTY_CALCULATION.

Обновляет сумму заказа после расчёта внешней лояльности.

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

1 PUT /orders/{id}

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

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

Уникальный идентификатор заказа в системе SWiP.

merchantDiscount

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

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

merchantPoints

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

Баллы для списания, которые предоставляет мерчант.

purcases

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

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

total

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

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

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

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 { "merchantDiscount": 0, // cкидка, которую предоставляет мерчант "merchantPoints": 0, // баллы для списания, которые предоставляет мерчант "points": { // расширенная версия баллов, для указания: "added": 0, // полученных баллов; "removed": 0, // списанных баллов; "total": 0 // оставшихся баллов. }, "purchases": [ // список покупок { "amount": 0, "discount": 0, "id": "string", "merchantDiscount": 0, "name": "string", "price": 0, "productId": "string", "quantity": 0, "unit": "string", } ], "total": 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 { "apiVersion": 3, "authorizationCode": "string", "cashback": 0.0, "closeAmount": 0.0, "customerId": null, "discountCard": "string", "error": "string", "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantCash": "88", "merchantCashier": "Маслова Вера", "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144", "merchantCategory": "Электроника", "merchantCommission": 0, "merchantDiscount": 0, "merchantId": "VZLT", "merchantName": "shop", "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantOrderNumber": "11", "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381", "merchantStore": "3", "orderNumber": "28048058915136358726242016980679", "orderStatus": "OPEN", "paid": 0.0, "pan": "string", "paymentMethod": "CARD", "paymentSystem": "MIR", "purchases": [ { "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78", "merchantDiscount": 0, "name": "Sprite 0,33 л", "productId": null, "quantity": 0, "unit": "string", "price": 50.0, "amount": 50.0, } ], "refunded": 0, "rrn": "string", "saleDate": 1540485815026, "sessionCode": "https://swip.one/?qr=6794742", "slip": "...very long text...", "swipDiscount": 0, "terminalNo": "string", "total": 50.0, "totalOriginal": 50.0, "unconfirmed": 0.0 }

Закрыть заказ

Закрытие заказа (базовый)

Вызывает базовый метод закрытия заказа.

Метод закрытия заказа может быть вызван только один раз. В теле запроса необходимо обязательно передать сумму к закрытию. В случае ошибки в процессе закрытия или отсутствия суммы к закрытию, деньги за заказ будут возвращены.
Если этот метод не был вызван в течение 10 минут после поступления денежных средств на кассу, то деньги за заказ будут возвращены.

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

1 POST /orders/{id}/actions/close

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

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

Уникальный идентификатор заказа в системе SWiP.

amount

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

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

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

1 2 3 { "amount":50.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 { "apiVersion": 3, "authorizationCode": "string", "cashback": 0.0, "closeAmount": 0.0, "customerId": null, "discountCard": "string", "error": "string", "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantCash": "88", "merchantCashier": "Маслова Вера", "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144", "merchantCategory": "Электроника", "merchantCommission": 0, "merchantDiscount": 0, "merchantId": "VZLT", "merchantName": "shop", "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantOrderNumber": "11", "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381", "merchantStore": "3", "orderNumber": "28048058915136358726242016980679", "orderStatus": "OPEN", "paid": 0.0, "pan": "string", "paymentMethod": "CARD", "paymentSystem": "MIR", "purchases": [ { "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78", "merchantDiscount": 0, "name": "Sprite 0,33 л", "productId": null, "quantity": 0, "unit": "string", "price": 50.0, "amount": 50.0, } ], "refunded": 0, "rrn": "string", "saleDate": 1540485815026, "sessionCode": "https://swip.one/?qr=6794742", "slip": "...very long text...", "swipDiscount": 0, "terminalNo": "string", "total": 50.0, "totalOriginal": 50.0, "unconfirmed": 0.0 }

Закрытие заказа (опциональный)

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

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

1 POST /orders/{id}/actions/confirm-and-close

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

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

Уникальный идентификатор заказа в системе SWiP.

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

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

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

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 { "apiVersion": 3, "authorizationCode": "string", "cashback": 0.0, "closeAmount": 0.0, "customerId": null, "discountCard": "string", "error": "string", "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantCash": "88", "merchantCashier": "Маслова Вера", "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144", "merchantCategory": "Электроника", "merchantCommission": 0, "merchantDiscount": 0, "merchantId": "VZLT", "merchantName": "shop", "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantOrderNumber": "11", "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381", "merchantStore": "3", "orderNumber": "28048058915136358726242016980679", "orderStatus": "OPEN", "paid": 0.0, "pan": "string", "paymentMethod": "CARD", "paymentSystem": "MIR", "purchases": [ { "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78", "merchantDiscount": 0, "name": "Sprite 0,33 л", "productId": null, "quantity": 0, "unit": "string", "price": 50.0, "amount": 50.0, } ], "refunded": 0, "rrn": "string", "saleDate": 1540485815026, "sessionCode": "https://swip.one/?qr=6794742", "slip": "...very long text...", "swipDiscount": 0, "terminalNo": "string", "total": 50.0, "totalOriginal": 50.0, "unconfirmed": 0.0 }

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

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

Данный метод возвращает заказы только в статусе CLOSED.

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

1 GET /orders

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

Параметр

Тип

Описание

Параметр

Тип

Описание

from

queryParam, long

Дата начала периода (в миллисекундах с 01.01.1970).

to

queryParam, long

Дата окончания периода (в миллисекундах с 01.01.1970).

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

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

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

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

1 2 3 4 5 6 7 8 9 10 11 [ { order 1 }, { order 2 }, { order N } ]

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

Создание возврата возможно только для заказов в статусе CLOSED.

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

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

1 POST /refunds

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

Параметр

Тип

Описание

Параметр

Тип

Описание

amount

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

Сумма возврата.

merchantOrderId

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

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

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

1 2 3 4 { "amount":25.00, "merchantOrderId":"d30ceaab-cc06-4f7c-bc58-2e86d336d7b3" }

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

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

1 2 3 4 5 6 { "status": "SUCCESS", // or FAIL "slip": "string", // текст с банковской информацией о платеже "description": "Some description", // описание ошибки "code": 0 // номер ошибки в системе SWIP }

Отмена оплаты

Отменяет оплату для заказов в статусе CLOSED.

Данный метод выполняет горячую отмену платежа, по которому денежные средства были захолдированы и ещё не списаны. Денежные средства замораживаюся на 1 час. Если списание было проведено, вернется ошибка с кодом 27. В таком случае необходимо выполнить возврат.

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

1 POST /reverses

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

Параметр

Тип

Описание

Параметр

Тип

Описание

amount

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

Сумма отмены оплаты.

merchantOrderId

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

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

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

1 2 3 4 { "amount":25.00, "merchantOrderId":"d30ceaab-cc06-4f7c-bc58-2e86d336d7b3" }

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

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

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

1 2 3 4 5 6 { "status": "SUCCESS", // or FAIL "slip": "string", // текст с банковской информацией о платеже "description": "Some description", // описание ошибки "code": 0 // номер ошибки в системе SWIP }

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

Данный метод необходим в случае тайм-аута на кассе или других причин, по которым надо выполнить отмену.

Отменяет заказ, находящийся в статусе OPEN (до проведения оплаты на кассе).

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

1 POST /orders/{id}/actions/close

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

Параметр

Тип

Описание

Параметр

Тип

Описание

id

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

Уникальный идентификатор заказа в системе SWiP.

amount

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

Сумма, которую касса передает к отмене.

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

1 2 3 { "amount":0.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 { "apiVersion": 3, "authorizationCode": "string", "cashback": 0.0, "closeAmount": 0.0, "customerId": null, "discountCard": "string", "error": "string", "id": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantCash": "88", "merchantCashier": "Маслова Вера", "merchantCashierId": "77527945-9a53-4849-a732-bd8736b39144", "merchantCategory": "Электроника", "merchantCommission": 0, "merchantDiscount": 0, "merchantId": "VZLT", "merchantName": "shop", "merchantOrderId": "1374289e-12fd-47e1-b111-0c6ae5568ff1", "merchantOrderNumber": "11", "merchantProfileImageId": "175bdc4f-9c3d-4465-89e0-a5bce381d381", "merchantStore": "3", "orderNumber": "28048058915136358726242016980679", "orderStatus": "OPEN", "paid": 0.0, "pan": "string", "paymentMethod": "CARD", "paymentSystem": "MIR", "purchases": [ { "id": "b314fd4e-df92-427b-a2f9-1da10dcefb78", "merchantDiscount": 0, "name": "Sprite 0,33 л", "productId": null, "quantity": 0, "unit": "string", "price": 50.0, "amount": 50.0, } ], "refunded": 0, "rrn": "string", "saleDate": 1540485815026, "sessionCode": "https://swip.one/?qr=6794742", "slip": "...very long text...", "swipDiscount": 0, "terminalNo": "string", "total": 50.0, "totalOriginal": 50.0, "unconfirmed": 0.0 }

Сохранить настройки кассы

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

Сохраняет настройки кассы на сервере. На данный момент используется для сохранения QR-кода.

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

1 PUT /merchant-settings/{settingName}

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

Параметр

Тип

Описание

Параметр

Тип

Описание

settingName

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

Название настройки (QR).

settingValue

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

Значение настройки (текстовое значение QR-кода).

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

1 2 3 4 { "settingName": "string", "settingValue": "string" }

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

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

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

1 2 3 4 5 6 7 { "cashId": "string", "merchantId": "string", "settingName": "string", "settingValue": "string", "storeId": "string" }

Получить настройки кассы

Этот метод является опциональным и необходим, если настройки кассы были сохранены на сервере.

Запрашивает на сервере значение прикрепленного к кассе QR-кода.

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

1 GET /merchant-settings/{settingName}

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

Параметр

Тип

Описание

Параметр

Тип

Описание

settingName

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

Название настройки (QR).

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

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

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

1 2 3 4 5 6 7 { "cashId": "string", "merchantId": "string", "settingName": "string", "settingValue": "string", "storeId": "string" }

Полный список методов

HTTP-метод

Путь

Параметры

Тело HTTP-запроса

Ответ

Описание

HTTP-метод

Путь

Параметры

Тело HTTP-запроса

Ответ

Описание

POST

/orders



order

order

Чтобы отправить заказ на оплату, необходимо создать объект заказа - Order. Он содержит всю необходимую информацию для проведения оплаты. В ответ на запрос придет тот же заказ с проставленными полями: id - SWiP orderid, sessionCode. Если sessionCode был отправлен пустым, то обратно вернется заполненное поле, его надо напечатать в пречеке или показать на экране (кассовом) покупателю.

GET

/orders/{id}

id



order

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

GET

/orders/{id}/status

id



1 2 3 4 5 6 7 8 { "totalOriginal":210.0, "total":210.0, "paid":0.0, "unconfirmed":0.0, "refunded":0.0, "status":"CLOSED" }

 

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

POST

/orders/{id}/actions/close

id

{"amount":50.0}

order

Вызывает метод закрытия заказа.

POST

/orders/{id}/actions/confirm-and-close

id



order

Подтверждает и закрывает заказ.

GET

/orders





list<orders>

Запрашивает список заказов за текущий день

POST

/orders/{id}/actions/close

id

{"amount":0.0}

 

Отменяет неоплаченный заказ.

POST

/refunds



1 2 3 4 {   "amount": 100.00,   "merchantOrderId": "" }
1 2 3 4 5 6 { "status": "SUCCESS", "slip": "", "description": "", "code": "" }

Возвращает успешно завершенный платеж по уникальному идентификатору заказа. Создание возврата возможно только для заказов в статусе CLOSED. Можно возвращать оплату по заказу полностью или частично.

POST

/reverses



1 2 3 4 { "amount": 100.00, "merchantOrderId": "" }
1 2 3 4 5 6 { "status": "SUCCESS", "slip": "", "description": "", "code": "" }

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

PUT

/merchant-settings/{settingName}

settingName

1 2 3 4 { "settingName": "string", "settingValue": "string" }
1 2 3 4 5 6 7 { "cashId": "string", "merchantId": "string", "settingName": "string", "settingValue": "string", "storeId": "string" }

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

Метод для сохранения настроек кассы на сервере. На данный момент используется для сохранения QR-кода.

GET

/merchant-settings/{settingName}

settingName

 

1 2 3 4 5 6 7 { "cashId": "string", "merchantId": "string", "settingName": "string", "settingValue": "string", "storeId": "string" }

Этот метод является опциональным и необходим, если настройки кассы были сохранены на сервере.

Запрашивает на сервере значение прикрепленного к кассе QR-кода.