Фискализация
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": 2025
},
"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:mm: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": 2024,
"token_provider": "apple_pay" // если транзакция была проведена через Apple Pay, null во всех других случаях
},
"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": 2023,
"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": 2015,
"token_provider": "apple_pay" // если транзакция была проведена через Apple Pay, null во всех других случаях
},
"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",
}