NAV
Example

Сводка изменений

Версия 3.3.8 от 15.06.2023

В этом разделе отражены изменения документа, внесенные с 15.06.2023 года.

Номер версии Раздел Описание Дата изменения
3.3.8 Весь документ Добавлена документация по фискализации в Казахстане 2023-06-15

Онлайн-касса для интернет-расчетов

Условия успешного создания чека

Отправка покупателю онлайн-чека

На выбор покупателя кассовый чек необходимо отправить в письме на e-mail адрес или в СМС (Viber/WhatsApp/Telegram) сообщении на номер телефона. При формировании корректного запроса на отправку чека, при условии передачи e-mail адреса или номера телефона покупателя, или при самостоятельном создании чека из личного кабинета — все необходимые реквизиты система передает в уведомлении Receipt.

Момент отправки чека

Чек должен быть отправлен покупателю в момент расчета. Для одностадийных платежей чек формируется сразу же после прохождения оплаты, для двустадийных (c холдированием) — при подтверждении операции.

API Кассы

API для касcы — программный интерфейс системы для взаимодействия с онлайн-кассой.

Интерфейс работает по адресу api.tiptoppay.kz и поддерживает функции для фискализации кассы, а также формирования и выдачи кассовых чеков.

Архитектура

API использует REST архитектуру. Параметры передаются методом POST в формате JSON, кодировке UTF-8 с обязательным указанием заголовка Content-Type: application/json.

Ответ система выдает в JSON формате, который как минимум включает в себя два параметра: Success и Message:

{ "Success": false, "Message": "Invalid Amount value" }

Первый параметр указывает на результат выполнения запроса – успешно или нет, второй может содержать дополнительную информацию.

Аутентификация запросов

Для аутентификации запроса используется HTTP Basic Auth — отправка логина и пароля в заголовке HTTP-запроса. В качестве логина используется Public ID, в качестве пароля — API Secret. Оба этих значения можно получить в личном кабинете.

Идемпотентность API

Идемпотентность — свойство API при повторном запросе выдавать тот же результат, что на первичный без повторной обработки. Это значит, что вы можете отправить несколько запросов к системе с одинаковым идентификатором, при этом обработан будет только один запрос, а все ответы будут идентичными. Таким образом реализуется защита от сетевых ошибок, которые приводят к созданию дублированных записей и действий.

Для включения идемпотентности необходимо в запросе к API передавать заголовок с ключом X-Request-ID, содержащий уникальный идентификатор. Формирование идентификатора запроса остается на вашей стороне — это может быть guid, комбинация из номера заказа, даты и суммы или любое другое значение на ваше усмотрение.

Каждый новый запрос, который необходимо обработать, должен включать новое значение X-Request-ID. Обработанный результат хранится в системе в течение 1 часа.

Формирование кассового чека

Метод формирования кассового чека.

Адрес метода:
https://api.tiptoppay.kz/kkt/receipt

Параметры запроса:

Параметр Формат Применение Описание
Inn Строка Обязательный ИИН/БИН вашей организации или ИП, на который зарегистрирована касса
Type Строка Обязательный Признак расчета, см. ниже
CustomerReceipt JSON Обязательный Состав чека см. ниже
InvoiceId Строка Необязательный Номер заказа в вашей системе
AccountId Строка Необязательный Идентификатор пользователя в вашей системе

При указании e-mail адреса или номера телефона плательщика, система автоматически отправит письмо с чеком или сообщение со ссылкой на чек. Вы также можете не указывать контакты, а самостоятельно отправлять покупателю чек в электронной форме с указанием фискальных реквизитов, полученных в уведомлении Receipt.

Type

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

Тип Признак расчета Описание
Income Приход Выдается при получении средств от покупателя (клиента)
IncomeReturn Возврат прихода Выдается при возврате покупателю (клиенту) средств, полученных от него
Expense Расход Выдается при выдаче средств покупателю (клиенту)
ExpenseReturn Возврат расхода Выдается при получении средств от покупателя (клиента), выданных ему

CustomerReceipt

Параметры формирования чека/состав чека.
Объект CustomerReceipt также может быть передан в параметре Data с вызовом виджета, либо в любом другом платёжном методе TipTop Pay (например, оплата по криптограмме, по токену, подтверждении оплаты, возвратах денежных средств, изменений подписки и др.) для формирования чека прихода при успешном платеже.

Параметр Формат Применение Описание
Items JSON Обязательный Содержимое позиций чека, см. ниже. Действует ограничение на максимальное количество позиций в чеке (100 штук). Если их больше - пробьется несколько чеков максимум по 100 позиций в каждом.
TaxationSystem Строка Обязательный Система налогообложения (необязательный, если у вас одна система налогообложения), см. ниже
Amounts JSON Обязательный Общая сумма платежа или возврата, см. ниже
CalculationPlace Строка Необязательный Место осуществления расчёта
Email Строка Необязательный E-mail покупателя для отправки чека
Phone Строка Необязательный Телефон покупателя в формате без скобок и дефисов
CustomerInn Строка Необязательный ИИН/БИН покупателя
isBso Булевый Необязательный true, если чек является бланком строгой отчётности
CashierName Строка Необязательный Имя кассира, если не передать будет использовано значение указанное в настройке кассира в ЛК, иначе “Сист. Администратор”
AdditionalReceiptInfos Массив строк Необязательный Дополнительная информация общая для чека, многострочная
AdditionalReceiptRequisite Строка Необязательный Дополнительный реквизит чека (тег 1192)

Items

Параметры услуг/товарных позиций в чеке.

Параметр Формат Применение Описание
Label Строка Обязательный Наименование товара или услуги
Price Строка Обязательный Цена за единицу товара/услуги
Quantity Строка Обязательный Количество
Vat Строка Обязательный Ставка НДС услуги/товара
Amount Строка Обязательный Price * Quantity c учетом скидки
Method Строка Необязательный Способ расчёта, см. ниже
Object Строка Необязательный Предмет расчёта, см. ниже
MeasurementUnit Строка Необязательный Единица измерения.
Excise Строка Необязательный Сумма акциза
AdditionalPositionInfo Строка Необязательный Дополнительная информация внутри конкретной позиции чека
RawMarkCode Строка Необязательный Код маркировки
GroupSeparator Строка Необязательный Разделитель GS
Vat

Значения ставки НДС.

Код Описание
null или не указано НДС не облагается
0 НДС 0%
12 НДС 12%
Method

Признак способа расчета.

Код Описание
0 Unknown, неизвестный способ расчета
1 FullPrepayment, предоплата 100%
2 PartialPrepayment, предоплата
3 AdvancePay, аванс
4 FullPay, полный расчёт
5 PartialPayAndCredit, частичный расчёт и кредит
6 Credit, передача в кредит
7 CreditPayment, оплата кредита
Object

Признак предмета расчета.

Код Описание
0 Unknown, неизвестный предмет оплаты
1 Commodity, товар
2 ExcisedCommodity, подакцизный товар
3 Job, работа
4 Service, услуга
5 GamblingBet, ставка азартной игры
6 GamblingWin, выигрыш азартной игры
7 LotteryTicket, лотерейный билет
8 LotteryWin, выигрыш лотереи
9 RidAccess, предоставление РИД
10 Payment, платеж
11 AgentReward, агентское вознаграждение
12 Composite, Выплата
13 Another, иной предмет расчета
14 PropertyLaw, Имущественное право
15 NonOperatingIncome, Внереализационный доход
16 InsuranceContributions, Страховые взносы
17 TradeFee, Торговый сбор
18 ResortFee, Курортный сбор
19 CautionMoney, Залог
20 ExpensesIncurred, Расход
21 ContributionsOnIp, Взносы на обязательное пенсионное страхование ИП
22 ContributionsSimple, Взносы на обязательное пенсионное страхование
23 ContributionsMedical, Взносы на обязательное медицинское страхование ИП
24 ContributionsMedicalSimple, Взносы на обязательное медицинское страхование
25 ContributionsSocial, Взносы на обязательное социальное страхование
26 CasinoPayment, Платеж казино
27 CashWithdrawal, Выдача денежных средств
30 Atnm, АТНМ
31 Atm, АТМ
32 Tnm, ТНМ
33 Tm, ТМ
ProductCodeData

Данные маркировки товара.

Параметр Формат Применение Описание
CodeProductNomenclature Строка Необязательный HEX представление штрих/бар кода маркировки целиком

TaxationSystem

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

Код Система налогообложения
0 Общеустановленный режим налогообложения
1 СНР на основе упрощенной декларации
4 СНР на основе патента

Amounts

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

Параметр Формат Применение Описание
Cash Строка Необязательный Сумма оплаты наличными деньгами
Electronic Строка Необязательный Сумма оплаты электронными деньгами
AdvancePayment Строка Необязательный Сумма предоплаты
Credit Строка Необязательный Сумма постоплатой
Provision Строка Необязательный Сумма встречным предоставлением

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

{
    "Inn": "160240029779", // ИИН/БИН
    "InvoiceId": "1234567", // Номер заказа, необязательный
    "AccountId": "[email protected]", // Идентификатор пользователя, необязательный
    "Type": "Income", // Признак расчета
    "CustomerReceipt": {
        "Items": // Товарные позициии [
            {
                "label": "Наименование товара 1", // Наименование товара или услуги
                "price": 100.00, // Цена
                "quantity": 1.00, // Количество
                "amount": 100.00, // Сумма
                "vat": 0, // Ставка НДС
                "measurementUnit": "шт" // Единица измерения
            },
            {
                "label": "Наименование товара 2", // Наименование товара или услуги
                "price": 200.00, // Цена
                "quantity": 2.00, // Количество
                "amount": 300.00, // Сумма со скидкой 25%
                "vat": 10, // Ставка НДС
                "measurementUnit": "шт" // Единица измерения
            },
            {
                "label": "Наименование товара 3", //наименование товара или услуги
                "price": 300.00, // Цена
                "quantity": 3.00, // Количество
                "amount": 900.00, // Сумма
                "vat": 20, // Ставка НДС
                "measurementUnit": "шт" // Единица измерения
            }
        ],
        "calculationPlace": "www.my.kz", //Место осуществления расчёта
        "taxationSystem": 0, // Система налогообложения; необязательный, если у вас одна система налогообложения
        "email": "[email protected]", // e-mail покупателя, если нужно отправить письмо с чеком
        "phone": "", // Телефон покупателя в любом формате
        "isBso": false, // Чек является бланком строгой отчётности
        "amounts": {
            "electronic": 1300.00, // Сумма оплаты электронными деньгами
            "advancePayment": 0.00, // Сумма из предоплаты (зачетом аванса) (2 знака после запятой)
            "credit": 0.00, // Сумма постоплатой(в кредит) (2 знака после запятой)
            "provision": 0.00 // Сумма оплаты встречным предоставлением (сертификаты, др. мат.ценности) (2 знака после запятой)
            "cash": 0.00 // Сумма оплаты наличными деньгами (2 знака после запятой)
        },    
    }
}

Формирование чека является асинхронной операцией, поэтому в ответ на запрос API система сообщает, что чек поставлен в очередь и будет обработан кассой в течение нескольких секунд. Для получения результата операции, вы можете включить Receipt уведомление в личном кабинете. При постановке чека в очередь, ему присваивается уникальный идентификатор.

Пример ответа: запрос принят успешно:

{
    "Model": {
        "Id": "4c335bb5ee56455f916db6e95c0d196e",
        "ErrorCode": 0
    },
    "InnerResult": null,
    "Success": true,
    "Message": "Queued",
    "Warning": null
}

Пример ответа: запрос принят успешно (но имеется сообщение требующее внимания):

{
    "Model": {
        "Id": "4c335bb5ee56455f916db6e95c0d196e",
        "ErrorCode": 0
    },
    "InnerResult": null,
    "Success": true,
    "Message": "Queued",
    "Warning": "01801810008658: Буфер ФН переполнен - Необходима замена ФН"
}

Пример ответа: некорректный запрос:

{
    "Model": {
        "ErrorCode": -1
    },
    "InnerResult": null,
    "Success": false,
    "Message": "Компания с ИИН/БИН 7777777777 не найдена"
}

В случае ошибки в поле Model возвращается объект с полем ErrorCode (см. справочник)

Запрос статуса чека

Метод получения статуса чека.

Адрес метода:
https://api.tiptoppay.kz/kkt/receipt/status/get

Параметры запроса:

Параметр Формат Применение Описание
Id Строка Обязательный Идентификатор чека

Пример запроса:

{ "Id": "4c335bb5ee56455f916db6e95c0d196e" }

Пример ответа (чек успешно обработался):

{
   "Model": "Processed",
   "Success": true
}

Пример ответа (чек не пробился):

{
   "Model": "Error",
   "InnerResult": null,
   "Success": true,
   "Message": "Нет касс без признака БСО для организации с ИИН/БИН ..."
}

Пример ответ (чек в очереди):

{
   "Model": "Queued",
   "Success": true
}

Пример ответ (чек не найден):

{
   "Model": "NotFound",
   "Success": true
}

Получение данных чека

Метод получения детализации чека.

Адрес метода:
https://api.tiptoppay.kz/kkt/receipt/get

Параметры запроса:

Параметр Формат Применение Описание
Id Строка Обязательный Идентификатор чека

Пример запроса:

{ "Id": "4c335bb5ee56455f916db6e95c0d196e" }

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

{
    "Model": {
        "Email": "[email protected]",
        "Phone": null,
        "Items": [
            {
                "Label": "Товар 1",
                "Price": 100,
                "Quantity": 1,
                "Amount": 100,
                "Department": null,
                "Vat": 0,
                "EAN13": null,
                "AgentSign": null,
                "Method": 6,
                "Object": 3,
                "MeasurementUnit": "шт"
            },
            {
                "Label": "Товар 2",
                "Price": 220,
                "Quantity": 2.5,
                "Amount": 550,
                "Department": null,
                "Vat": 10,
                "EAN13": null,
                "AgentSign": 2,
                "Method": 0,
                "Object": 0,
                "MeasurementUnit": null
            },
            {
                "Label": "Товар 3",
                "Price": 150,
                "Quantity": 5,
                "Amount": 600,
                "Department": null,
                "Vat": 20,
                "EAN13": null,
                "AgentSign": null,
                "Method": 0,
                "Object": 0,
                "MeasurementUnit": null
            }
        ],
        "TaxationSystem": 2,
        "Amounts": null,
        "IsBso": false,
        "AdditionalData": {
            "Id": "4c335bb5ee56455f916db6e95c0d196e",
            "AccountId": "[email protected]"
            "Amount": 1150,
            "CalculationPlace": "www.my.kz",
            "CashierName": "test",
            "DateTime": "2018-11-14T16:19:33",
            "DeviceNumber": "00000000000000000001",
            "DocumentNumber": "1323",
            "FiscalNumber": "9999078900005430",
            "FiscalSign": "13223",
            "InvoiceId": "1322223",
            "OfdReceiptUrl": "http://url.com/adress",
            "OrganizationInn": "160240029779",
            "QrCodeUrl": "https://qr.tiptoppay.kz/receipt?q=t%3d20181205T185000%26s%3d99.00%26fn%3d9999078900005430%26i%3d157347%26fp%3d1016954666%26n%3d1",
            "RegNumber": "322223",
            "SenderEmail": "[email protected]",
            "SessionCheckNumber": "12223",
            "SessionNumber": "1",
            "TransactionId": 14442,
            "Type": "Income",
        }
    },
    "InnerResult": null,
    "Success": true,
    "Message": null
}

Уведомления

Уведомление — HTTP-запрос от системы к вашему сайту. Подобные запросы также называют callback или webhook.

Receipt

Выполняется после выдачи кассового чека.

Служит для информирования о сформированных онлайн-чеках: система отправляет запрос на адрес ТСП с информацией о чеке, а сайт должен зафиксировать информацию.

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

Параметр Формат Применение Описание
Id Строка Обязательный Уникальный идентификатор чека
DocumentNumber Целое число Обязательный Номер чека
SessionNumber Целое число Обязательный Номер смены
Number Целое число Обязательный Номер чека в смене
FiscalSign Строка Обязательный Фискальный признак документа
DeviceNumber Целое число Обязательный Заводской номер ККТ
RegNumber Строка Обязательный Регистрационный номер ККТ
FiscalNumber Строка Обязательный Номер фискального накопителя
Inn Число Обязательный ИИН/БИН
Type Строка Обязательный Признак расчета, см. справочник
Ofd Строка Обязательный Наименование оператора фискальных данных
Url Строка Обязательный URL адрес с копией чека
TransactionId Целое число Необязательный Идентификатор транзакции
Amount Число Обязательный Сумма чека
DateTime yyyy-MM-dd HH:mm:ss Обязательный Дата/время выдачи чека во временной зоне UTC
InvoiceId Строка Необязательный Номер заказа
AccountId Строка Необязательный Идентификатор пользователя
Receipt JSON Обязательный Состав чека
CalculationPlace Строка Необязательный Место осуществления расчетов
CashierName Строка Необязательный Имя кассира
SettlePlace Строка Необязательный место нахождения (установки) ккм

В ответ на запрос система ожидает получить ответ в JSON формате с обязательным параметром code:

{"code":0}

Код определяет результат обработки сервером ТСП уведомления о чеке и может принимать единственное значение:

Код Значение
0 Чек зарегистрирован

Принцип работы и проверка уведомлений

Параметры передаются методом POST или GET в теле запроса в формате «ключ=значение».

Уведомление receipt содержит 2 HTTP-заголовка X-Content-HMAC и Content-HMAC, в котором находится проверочное значение запроса, вычисленное с помощью алгоритма HMAC. Отличие между ними только в том, что первый генерируется из URL decoded (или не encoded) параметров, а второй генерируется из URL encoded параметров (что может вызывать проблемы). Если вам необходимо проверять подлинность и целостность уведомлений, вы можете вычислить проверочное значение на своей стороне и сравнить с тем, что пришло в запросе. Совпадение подтверждает, что уведомление было отправлено от нас и пришло к вам в оригинальном виде.

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

Примеры вычисления HMAC на разных языках программирования.

Адрес, с которого система отправляет уведомления — 91.216.178.243.

Для вас это означает что:

Более подробно, как отказаться от SSL3. После 8 июня https-уведомления на сервера, поддерживающие только SSL3, могут не доставляться.




Справочники

Коды временных зон

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

Код Название
HST (UTC-10:00) Гавайи
AKST (UTC-09:00) Аляска
PST (UTC-08:00) Тихоокеанское время (США и Канада)
MST (UTC-07:00) Горное время (США и Канада)
CST (UTC-06:00) Центральное время (США и Канада)
EST (UTC-05:00) Восточное время (США и Канада)
AST (UTC-04:00) Атлантическое время (Канада)
BRT (UTC-03:00) Бразилия
UTC (UTC) Время в формате UTC
GMT (UTC) Дублин, Лиссабон, Лондон, Эдинбург
CET (UTC+01:00) Амстердам, Берлин, Берн, Вена, Рим, Стокгольм
CET (UTC+01:00) Белград, Братислава, Будапешт, Любляна, Прага
CET (UTC+01:00) Брюссель, Копенгаген, Мадрид, Париж
CET (UTC+01:00) Варшава, Загреб, Сараево, Скопье
EET (UTC+02:00) Афины, Бухарест
EET (UTC+02:00) Вильнюс, Киев, Рига, София, Таллин, Хельсинки
EET (UTC+02:00) Восточная Европа
EET (UTC+02:00) Калининград (RTZ 1)
MSK (UTC+03:00) Волгоград, Москва, Санкт-Петербург (RTZ 2)
MSK (UTC+03:00) Минск
AZT (UTC+04:00) Баку
AMT (UTC+04:00) Ереван
SAMT (UTC+04:00) Ижевск, Самара (RTZ 3)
GET (UTC+04:00) Тбилиси
TJT (UTC+05:00) Ашхабад, Ташкент
YEKT (UTC+05:00) Екатеринбург (RTZ 4)
ALMT (UTC+06:00) Астана, Алматы
NOVT (UTC+06:00) Новосибирск (RTZ 5)
KRAT (UTC+07:00) Красноярск (RTZ 6)
HKT (UTC+08:00) Гонконг, Пекин, Урумчи, Чунцин
IRKT (UTC+08:00) Иркутск (RTZ 7)
SGT (UTC+08:00) Куала-Лумпур, Сингапур
ULAT (UTC+08:00) Улан-Батор
YAKT (UTC+09:00) Якутск (RTZ 8)
VLAT (UTC+10:00) Владивосток, Магадан (RTZ 9)
SAKT (UTC+11:00) Чокурдах (RTZ 10)
ANAT (UTC+12:00) Анадырь, Петропавловск-Камчатский (RTZ 11)

Тип уведомления

В таблице ниже представлены тип уведомления.

Код Название
Receipt Receipt

Коды ошибок

В таблице ниже представлены коды ошибок при формировании онлайн-чека.

Код Описание
-1 Неизвестная ошибка
2 Отсутствует ККТ для фискализации транзакции для данной организации
3 Переданная система налогообложения не установлена ни в одной кассе для данной организации
4 Переданы не все необходимые данные агента
5 Отсутствует ИИН/БИН поставщика или телефон поставщика при агентском расчете
6 Оформление услуг не разрешено при регистрации ККТ или телефон покупателя передан в неверном формате
7 Неверный формат ИИН/БИН поставщика
8 Ресурс хранения документов исчерпан (ФН переполнен)
9 Ошибка агентских данных
10 Не зашифрованные персональные данные
11 Не передан ИИН/БИН
12 Отсутствует информация о товарах/услугах
13 Сумма по всем способам оплаты меньше итога чека
14 Вносимая безналичной оплатой сумма больше суммы чека
15 Нет подходящей ККМ для данной организации
16 Нет касс с подходящим терминалом
17 Нет касс с признаком БСО
18 Нет касс без признака БСО
19 Нет касс поддерживающих наличный рассчет
20 Нет касс с агентским признаком
21 Нет касс с поддержкой тега - Дополнительный реквизит пользователя
22 Превышен лимит тестовых чеков за день
23 Неверный формат цены/суммы - не более двух знаков после точки
24 Неверный формат email

Коды предупреждений

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

Код Описание
5 Ошибка кассы

Модули CMS Kassir

Кассовые модули от TipTop Pay предоставляют инструменты, которые легко интегрируются с вашей CMS-системой или конструктором сайтов. Это позволит вам быстро начать формировать чеки и облегчит процесс настройки.

1C Битрикс

GitLab

Возможности:

Совместимость:

WooCommerce

GitLab

Возможности:

Совместимость: