Фискализация
API bePaid позволяет отправить фискальные данные в запросе финансовой транзакции и получить в ответе ссылку на фискальный чек.
Дополнительные параметры запроса для фискализации
Чтобы отправить фискальные данные, вам необходимо передать дополнительные параметры в объекте fiscalization в запросе финансовой транзакции (request.fiscalization для оплаты и списания средств или checkout.fiscalization для создания токена платежа).
Для банковских карт, фискализацию поддерживают следующие транзакции:
- оплата;
- возврат средств;
- списание средств;
- создание токена платежа.
Для альтернативных способов оплаты, фискализацию поддерживают следующие транзакции:
- оплата;
- возврат средств;
- списание средств.
Вариант интеграции Buhta KZ
Запрос
Info
Обратите внимание, что для корректной обработки запроса фискализации, необходимо указать ИНН (идентификационный номер налогоплательщика) в поле Налоговый номер при создании/редактировании торговца/магазина в личном кабинете системы. Для обработки запроса будет использован Налоговый номер магазина. При его отсутствии в личном кабинете, будет использован Налоговый номер торговца.
В таблице ниже указаны параметры и их возможные значения для объекта fiscalization.
|
|||||||||||||||||||||||||||||||||||||||||
Пример запроса на платеж с фискализацией
{
"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": 2028
},
"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": "Номенклатурный код товара"
}
]
}
}
}
Ответ
|
|||||||||||||||||||||||||||||||||||||||||
Пример успешного ответа. Финансовая транзакция успешна и фискальные данные получены.
{
"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": 2028,
"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": 2028,
"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": 2028,
"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",
}
Возврат средств
Возврат средств с применением фискализации возможен для типов транзакций оплата и списание средств. Возвраты можно осуществить как с помощью API запроса, так и в личном кабинете торговца.
Info
Возврат с фискализацией доступен только на полную сумму родительской транзакции.
Возврат средств через API
Для выполнения возврата с фискализацией необходимо в стандартном запросе на возврат средств указать параметр "fiscalization": true.
Пример запроса на возврат с фискализацией
{
"request": {
"amount": 10,
"parent_uid": "ec331643-d17f-4e3c-9a13-b15191e28193",
"reason": "Client request",
"fiscalization": true
}
}
Возврат средств через личный кабинет
Возврат можно осуществить на странице детальной информации о транзакции. Для этого выполните следующие шаги:
1) Найдите нужную транзакцию оплаты или списания средств в разделе Платежи (Платежи > нажать на UID транзакции)
2) Нажмите Возврат средств
3) В открывшемся модальном окне укажите сумму возврата, причину возврата и выберете опцию через сервис фискализации. В личном кабинете возврат с фискализацией всегда выполняется на полную сумму родительской транзакции, независимо от указанной суммы.
4) На странице детальной информации родительской транзакции появится информация о возврате с фискальными данными.
