Перейти к содержанию

Фискализация

API bePaid позволяет отправить фискальные данные в запросе финансовой транзакции и получить в ответе ссылку на фискальный чек.

Дополнительные параметры запроса для фискализации

Чтобы отправить фискальные данные, вам необходимо передать дополнительные параметры в объекте fiscalization в запросе финансовой транзакции.

Для банковских карт, фискализацию поддерживают следующие транзакции:
- оплата;
- возврат средств;
- списание средств.

Для альтернативных способов оплаты, фискализацию поддерживают следующие транзакции:
- оплата;
- возврат средств;
- списание средств.

Вариант интеграции Buhta KZ

Запрос

Info

Обратите внимание, что для корректной обработки запроса фискализации, необходимо указать ИНН (идентификационный номер налогоплательщика) в поле Налоговый номер при создании/редактировании торговца/магазина в личном кабинете системы. Для обработки запроса будет использован Налоговый номер магазина. При его отсутствии в личном кабинете, будет использован Налоговый номер торговца.

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

Параметр Тип Описание
fiscalization object Секция параметров фискализации.
external_id string (255) Уникальный идентификатор транзакции в системе торговца.
positions * обязательный
 array Список предметов расчета, каждый элемент которого состоит из ряда параметров, например:
name * обязательный
 string (255) Наименование позиции в чеке.
type * обязательный
 string (24) Тип позиции в чеке.

Возможные значения:
product;
product_storno;
gambling_bet;

и другие.
amount * обязательный
 bigInteger Сумма позиции в чеке в минимальных денежных единицах. Сумма значений amount по всем позициям в чеке не должна быть больше значения основного параметра amount в запросе финансовой транзакции.
quantity * обязательный
 float (8) Количество однотипной позиции в чеке. Десятичное число с точностью до 6 символов после точки.
measure_unit_code *обязательный
 integer (6) Единица измерения для параметра quantity.
description string (510) Описание позиции в чеке.
nomenclature_code string (510) Номенклатурный код товара.
untaxed * обязательный
 boolean Если true, не участвует в расчете налогов. В этом случае, массив taxes не обязателен.

Если false, участвует в расчете налогов. В этом случае, массив taxes обязателен в запросе.
taxes *условно обязательный
 array Массив с данными о налогах. Обязателен за исключением случаев, когда "untaxed": true". Массив taxes должен быть указан только для одной позиции в чеке. Величина налога будет применена ко всем позициям в чеке, за исключением позиций, где "untaxed": true.
percent * обязательный
 string (2) Налоговая ставка. Например, "12" (12%, знак % не указывается).
type * обязательный
 string (255) Тип налога

Возможные значения:
vat - налог на добавленную стоимость;
city_tax - городской налог;
excise - акциз. Укажите это значение, если предмет расчета признается объектом налогообложения акцизами.

Если значение не передано, обрабатывается как vat.
id string (32) Идентификатор налога в системе торговца.
description string (510) Описание типа налога.
inclusive *обязательный
 boolean Если true или не указан, НДС уже включен в стоимость товара.

Если false, НДС не включен в стоимость товара.
Пример запроса на платеж с фискализацией 
{
    "request": {
        "amount": 1116,
        "currency": "KZT",
        "description": "T",
        "tracking_id": "your_uniq_number",
        "language": "en",
        "test": false,
        "credit_card": {
            "number": "4230864964638442",
            "verification_value": "123",
            "holder": "John Dose",
            "exp_month": 05,
            "exp_year": 2027
        },
        "fiscalization": {
            "external_id": "Идентификатор фискализации торговца",                
            "positions": [
                {
                    "name": "Название продукта",
                    "type": "service",
                    "amount": 100,
                    "quantity": 1.0,
                    "measure_unit_code": 796,
                    "description": "Описание продукта",
                    "untaxed": false,
                    "nomenclature_code": "Номенклатурный код товара",
                    "taxes": [
                        {
                            "id": "Идентификатор налога",
                            "percent": "12",
                            "type": "vat",
                            "description": "Описание налога",
                            "inclusive": true
                        }
                    ]
                },
                {
                    "name": "Название продукта2",
                    "type": "service",
                    "amount": 100,
                    "quantity": 1.0,
                    "measure_unit_code": 796,
                    "description": "Описание продукта",
                    "untaxed": true,
                    "nomenclature_code": "Номенклатурный код товара"
                }
            ]
        }
    }
}
Ответ
Параметр Тип Описание
fiscalization object Секция параметров фискализации.
type string Тип транзакции. Возможные значения: payment, refund, payout.
id string (36) Идентификатор транзакции в системе bePaid.
external_id string (255) Внешний идентификатор транзакции фискализации торговца.
status * обязательный
 string (255) Статус транзакции фискализации.

Возможные значения:
successful - успешно;
failed - ошибка проведения транзакции на стороне провайдера;
pending (или incomplete) - транзакция в процессе обработки;
error (или expired или deleted) - ошибка обработки транзакции в системе bePaid.
code * обязательный
 string (6) Код результата транзакции фискализации.
message *обязательный
 string (255) Сообщение для торговца о результате транзакции фискализации.
friendly_message *обязательный
 string (255) Сообщение для покупателя о результате транзакции фискализации.
receipts * обязательный
 array Массив чеков.
id string (255) Уникальный идентификатор чека в системе bePaid.
serial_id string (255) Последовательный номер чека в ККМ.
receipt_num string (255) Номер чека в системе bePaid.
created_at string Время и дата создания чека в системе bePaid. Формат: YYYY-MM-DDThh🇲🇲ssTZD, где YYYY – год (например, 2019), MM – месяц (например, 02), DD – день (например, 09), hh – часы (например, 18), mm – минуты (например, 20), ss – секунды (например, 45), TZD – часовой пояс (+hh:mm или –hh:mm относительно UTC).
ofd_id string (255) Уникальный идентификатор фискального чека в системе ОФД (оператора фискальных данных).
ofd_link string (1024) Ccылка на фискальный чек.
ofd_qr_code string (1024) QR код, ссылающийся на фискальный чек.
total_amount integer Сумма по чеку в минимальных денежных единицах.
receipt_info object Исходные данные из ответа bePaid или ОФД.
Пример успешного ответа. Финансовая транзакция успешна и фискальные данные получены. 
{
    "transaction": {
        "uid": "4107-310а0da80b",
        "status": "successful",
        "message": "Successfully processed",
        "amount": 100,
        "currency": "USD",
        "description": "Test order",
        "type": "payment",
        "tracking_id": "your_uniq_number",
        "language": "en",
        "payment_method_type": "credit_card",
        "customer": {
            "ip": "127.0.0.1",
            "email": "john@example.com"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "address": "1st Street",
            "country": "US",
            "city": "Denver",
            "zip": "96002",
            "state": "CO",
            "phone": null
        },
        "fiscalization": {
            "id":"string 36",
            "external_id": "string 255",
            "status": "success", 
            "message": "successfully",
            "friendly_message": "successfully",                    
            "receipts": [
                {
                    "id": "01gsstxpygv99zemh9t38cv8da",
                    "serial_id": "9",
                    "receipt_num": "1234567867233",
                    "created_at": "2023-02-21T11:14:44Z",
                    "ofd_id": "70600654",
                    "ofd_link": "link.com/receipt",
                    "ofd_qr_code": "link.com/receipt",
                    "total_amount": "18700",
                    "receipt_info": {
                        "kkm_id": 49,
                        "id": "01gsstxpygv99zemh9t38cv8da",
                        "shift_id": 2,
                        "serial_id": "9",
                        "serial_shift_id": "4",
                        "issue_time": "2023-02-21T11:14:44Z",
                        "operation_type": "OPERATION_TYPE_SALE",
                        "payment_type": "PAYMENT_TYPE_CARD",
                        "currency_code": "USD",
                        "subtotal_amount": "10000",
                        "total_amount": "10000",
                        "cashier_code": 6207,
                        "cashier_name": "Robot",
                        "receipt_num": "1234567890233",
                        "ofd_receipt_id": "706806547",
                        "ofd_qr_code": "link.com/receipt"
                    }
                },
                {
                    "id": "2222stxpygv99zemh9t38cv8da",
                    "serial_id": "9",
                    "receipt_num": "1234567867233",
                    "created_at": "2023-02-21T11:14:44Z",
                    "ofd_id": "706006547",
                    "ofd_link": "link.com/receipt",
                    "total_amount": "1400.0000",
                    "receipt_info": {
                        "kkm_id": 49,
                        "id": "01gsstxpygv99zemh9t38cv8da",
                        "shift_id": 2,
                        "serial_id": "9",
                        "serial_shift_id": "4",
                        "issue_time": "2023-02-21T11:14:44Z",
                        "operation_type": "OPERATION_TYPE_SALE",
                        "payment_type": "PAYMENT_TYPE_CARD",
                        "currency_code": "USD",
                        "subtotal_amount": "1400.0000",
                        "total_amount": "1400.0000",
                        "cashier_code": 6207,
                        "cashier_name": "Robot",
                        "receipt_num": "1234567867233",
                        "ofd_receipt_id": "706006547",
                        "ofd_qr_code": "link.com/receipt"
                    }
                }
            ]
        },
        "credit_card": {
            "holder": "John Doe",
            "stamp": "3709786942408b7701",
            "token": "40bd001563085fc35165329ea1f",
            "brand": "visa",
            "product": "Gold",
            "last_4": "0000",
            "first_1": "4",
            "exp_month": 05,
            "exp_year": 2027,
            "token_provider": "apple_pay" 
        },
        "receipt_url": "link.com",
        "additional_data": {
            "receipt_text": [
                "First line",
                "Second line"
            ]
        },
        "payment": {
            "auth_code": "654321",
            "bank_code": "00",
            "rrn": "999",
            "ref_id": "777888",
            "message": "The operation was successfully processed.",
            "gateway_id": 317,
            "billing_descriptor": "TEST GATEWAY BILLING DESCRIPTOR",
            "status": "successful"
        }
    }
}
Пример неуспешного ответа. Финансовая транзакция успешна, ошибка транзакции сервиса фискальных данных. 
{
    "transaction": {
        "uid": "4107-311b0da70b",
        "status": "successful",
        "message": "Successfully processed",
        "amount": 100,
        "currency": "USD",
        "description": "Test order",
        "type": "payment",
        "tracking_id": "your_uniq_number",
        "language": "en",
        "payment_method_type": "credit_card",
        "customer": {
            "ip": "127.0.0.1",
            "email": "john@example.com"
    },
    "billing_address": {
        "first_name": "John",
        "last_name": "Doe",
        "address": "1st Street",
        "country": "US",
        "city": "Denver",
        "zip": "96002",
        "state": "CO",
        "phone": null
    },
    "fiscalization": {
        "id": "string 36",
        "external_id": "string 255",
        "status": "failed",
        "code": "S.8025",
        "message": "Сумма позиций чека не равна сумме транзакции. Не удалось завершить транзакцию. Проверьте параметры запроса.",
        "friendly_message": "Сумма позиций чека не равна сумме транзакции. Не удалось завершить транзакцию. Обратитесь к продавцу для уточнения причины.",                
        "receipts": []
    },
    "credit_card": {
        "holder": "John Doe",
        "stamp": "3709786942408b7701",
        "token": "40bd001563085fc35165329ea165329e",
        "brand": "visa",
        "product": "Gold",
        "last_4": "0000",
        "first_1": "4",
        "exp_month": 05,
        "exp_year": 2027,
        "token_provider": "apple_pay"
    },
    "receipt_url": "link.com",
    "additional_data": {
        "receipt_text": [
            "First line",
            "Second line"
        ]
    },
        "payment": {
            "auth_code": "654321",
            "bank_code": "00",
            "rrn": "999",
            "ref_id": "777888",
            "message": "The operation was successfully processed.",
            "gateway_id": 317,
            "billing_descriptor": "TEST GATEWAY BILLING DESCRIPTOR",
            "status": "successful"
        }
    }
}
Пример неуспешного ответа. Финансовая транзакция не успешна, запрос на фискальные данные не был создан. 
{
    "transaction": {
        "uid": "4107-210b0a80b",
        "status": "failed",
        "message": "failed processed",
        "amount": 100,
        "currency": "USD",
        "description": "Test order",
        "type": "payment",
        "tracking_id": "your_uniq_number",
        "language": "en",
        "payment_method_type": "credit_card",
        "customer": {
            "ip": "127.0.0.1",
            "email": "john@example.com"
        },
        "billing_address": {
            "first_name": "John",
            "last_name": "Doe",
            "address": "1st Street",
            "country": "US",
            "city": "Denver",
            "zip": "96002",
            "state": "CO",
            "phone": null
        },
        "credit_card": {
            "holder": "John Doe",
            "stamp": "3709786942408b",
            "token": "40bd00156308",
            "brand": "visa",
            "product": "Gold",
            "last_4": "0000",
            "first_1": "4",
            "exp_month": 5,
            "exp_year": 2027,
            "token_provider": "apple_pay" 
        },
        "receipt_url": "link.com",
        "additional_data": {
            "receipt_text": [
                "First line",
                "Second line"
            ]
        },
        "payment": {
            "auth_code": "654321",
            "bank_code": "00",
            "rrn": "999",
            "ref_id": "777888",
            "message": "Payment was declined",
            "gateway_id": 317,
            "billing_descriptor": "TEST GATEWAY BILLING DESCRIPTOR",
            "status": "failed"
        }
    }
}
Пример успешного ответа. Финансовая транзакция успешна и фискальные данные получены. 
{
    "status": "success",
    "code": "S.0000", 
    "message": "successfully", 
    "friendly_message": "successfully",
    "type": "payment", 
    "amount": 100000000, 
    "id": "string 255", 
    "fiscalization": {
        "id":"string 36",
        "external_id": "string 255",
        "status": "success", 
        "code": "S.0000", 
        "message": "successfully", 
        "friendly_message": "successfully",                 
        "receipts": [
            {
                "id": "01gsstxpygv99tymh9t38cv8da",
                "serial_id": "9",
                "receipt_num": "1234567890233",
                "created_at": "2024-02-21T11:14:44Z",
                "ofd_id": "706806547",
                "ofd_link": "link.com/receipt",
                "ofd_qr_code": "link.com/receipt",
                "total_amount": "18700",
                "receipt_info": {
                    "kkm_id": 49,
                    "id": "01gsstxpygv99zemh9t38cv8da",
                    "shift_id": 2,
                    "serial_id": "9",
                    "serial_shift_id": "4",
                    "issue_time": "2023-02-21T11:14:44Z",
                    "operation_type": "OPERATION_TYPE_SALE",
                    "payment_type": "PAYMENT_TYPE_CARD",
                    "currency_code": "USD",
                    "subtotal_amount": "10000",
                    "total_amount": "10000",
                    "cashier_code": 6207,
                    "cashier_name": "Robot",
                    "receipt_num": "1234567890233",
                    "ofd_receipt_id": "706806547",
                    "ofd_qr_code": "link.com/receipt"
                }
            },
            {
                "id": "2222stxpygv99zemh9t38cv8da",
                "serial_id": "9",
                "receipt_num": "1234567890233",
                "created_at": "2023-02-21T11:14:44Z",
                "ofd_id": "706806547",
                "ofd_link": "link.com/receipt",
                "total_amount": "1400.0000",
                "receipt_info": {
                    "kkm_id": 49,
                    "id": "01gsstxpygv99zemh9t98cv8da",
                    "shift_id": 2,
                    "serial_id": "9",
                    "serial_shift_id": "4",
                    "issue_time": "2023-02-21T11:14:44Z",
                    "operation_type": "OPERATION_TYPE_SALE",
                    "payment_type": "PAYMENT_TYPE_CARD",
                    "currency_code": "USD",
                    "subtotal_amount": "1400.0000",
                    "total_amount": "1400.0000",
                    "cashier_code": 6207,
                    "cashier_name": "Robot",
                    "receipt_num": "1234567890233",
                    "ofd_receipt_id": "706806547",
                    "ofd_qr_code": "link.com/receipt"
                }
            }
        ]
    }
}
Пример неуспешного ответа. Финансовая транзакция успешна, ошибка транзакции сервиса фискальных данных. 
{
    "status": "success",
    "code": "S.0000",
    "message": "successfully",
    "friendly_message": "successfully",
    "type": "payment",
    "amount": 10000000000,
    "id": "string 255",
    "fiscalization": {
        "id": "string 36",
        "external_id": "string 255",
        "status": "failed",
        "code": "S.8025",
        "message": "Сумма позиций чека не равна сумме транзакции. Не удалось завершить транзакцию. Проверьте параметры запроса.",
        "friendly_message": "Сумма позиций чека не равна сумме транзакции. Не удалось завершить транзакцию. Обратитесь к продавцу для уточнения причины.",                
        "receipts": [
        {
            "id": "01gsstxpygv88zemh9t98cv8da",
            "serial_id": "9",
            "receipt_num": "1234567890233",
            "created_at": "2024-02-21T11:14:44Z",
            "ofd_id": "706806547",
            "ofd_link": "link.com/receipt",
            "ofd_qr_code": "link.com/receipt",
            "total_amount": "18700",
            "receipt_info": {
                "kkm_id": 49,
                "id": "01gsstxpygv99zem9t98cv8da",
                "shift_id": 2,
                "serial_id": "9",
                "serial_shift_id": "4",
                "issue_time": "2024-02-21T11:14:44Z",
                "operation_type": "OPERATION_TYPE_SALE",
                "payment_type": "PAYMENT_TYPE_CARD",
                "currency_code": "USD",
                "subtotal_amount": "10000",
                "total_amount": "10000",
                "cashier_code": 6207,
                "cashier_name": "Robot",
                "receipt_num": "1234567890233",
                "ofd_receipt_id": "706806547",
                "ofd_qr_code": "link.com/receipt"
                }
            },
            {
                "id": "2222stxpygv99zem9t38cv8da",
                "serial_id": "9",
                "receipt_num": "1234567890233",
                "created_at": "2023-02-21T11:14:44Z",
                "ofd_id": "706806547",
                "ofd_link": "link.com/receipt",
                "total_amount": "1400.0000",
                "receipt_info": {
                "kkm_id": 49,
                "id": "01gsstxpygv99zemh9t38cv8da",
                "shift_id": 2,
                "serial_id": "9",
                "serial_shift_id": "4",
                "issue_time": "2023-02-21T11:14:44Z",
                "operation_type": "OPERATION_TYPE_SALE",
                "payment_type": "PAYMENT_TYPE_CARD",
                "currency_code": "USD",
                "subtotal_amount": "1400.0000",
                "total_amount": "1400.0000",
                "cashier_code": 6207,
                "cashier_name": "Robot",
                "receipt_num": "1234567890233",
                "ofd_receipt_id": "706806547",
                "ofd_qr_code": "link.com/receipt"
                }
            }
        ]
    }
}
Пример неуспешного ответа. Финансовая транзакция не успешна, запрос на фискальные данные не был создан. 
{
    "status": "success", 
    "code": "F.0003", 
    "message": "Срок действия карты истек: Попросите клиента использовать действительную карту.", 
    "friendly_message": "Срок действия карты истек: Не удалось совершить транзакцию. Используйте действительную карту.", 
    "type": "payment", 
    "amount": 10000, 
    "id": "string 255",      
}