Fiscalization
bePaid API lets you send fiscalization information in the request of the financial transaction and receive a link to a fiscal receipt in the response.
Additional parameters for fiscalization
To send the fiscalization information, you need to send additional parameters in the fiscalization
object (request.fiscalization
for capture and payment or checkout.fiscalization
for payment token) in the financial transaction requests.
The following card transactions support fiscalization:
- payment;
- refund;
- capture;
- payment token.
For alternative payment methods, you can send fiscalization information in the following transactions:
- payment;
- refund;
- capture.
Buhta KZ integration option
Request
Info
Note that in order for the fiscalization request to be processed properly, it is required to specify TIN (taxpayer identification number) under Tax Id field in the back office system when editing/setting up a corresponding merchant and/or shop. The system will use the shop's Tax Id. If not specified, it will use the merchant's Tax Id.
The table below lists the request parameters and their description for this integration option for the fiscalization
object.
Parameter | Type | Description |
---|---|---|
fiscalization | object | A section of fiscalization parameters. |
external_id | string (255) | Unique transaction identifier in the merchant's system. |
positions * required |
array | A list of the receipt items where each item contains the following parameters: |
name * required |
string (255) | The name of the receipt item. |
type * required |
string (24) | Type of the receipt item. Possible values: product ; product_storno ; gambling_bet ;other values. |
amount * required |
bigInteger | Receipt item payment amount in minimal currency units. The sum of the amount values for all the receipt items must not exceed the transaction amount. |
quantity * required |
float (8) | The amount/number of the identical receipt items. A number with up to 6 decimal places. |
measure_unit_code *required |
integer (6) | Measure unit code for the value of quantity parameter. |
description | string (510) | Description of the receipt item. |
nomenclature_code | string (510) | Nomenclature code of the receipt item. |
untaxed * required |
boolean | If true , ignored when calculating taxes. In this case, the taxes array is not required. If false , participates in the calculation of taxes. In this case, the taxes array is required in the request. |
taxes *conditionally required |
array | Array with the taxes data. Required except for the cases when "untaxed": true . Taxes array must be specified only for one position in the receipt. The specified tax will be applied to all the receipt items except for those that have "untaxed": true |
percent * required |
string (2) | The tax rate. For example, "12" (12%, % sign must not be sent). |
type * required |
string (255) | Tax type Possible values: vat - value added tax;city_tax - city tax;excise - excise, send this value if the receipt item is subject to excise tax. If not sent, processed as vat . |
id | string (32) | Tax identifier in the merchant's system. |
description | string (510) | Description of the tax type. |
inclusive * required |
boolean | If true or not specified, VAT is already included in the receipt item price.If false , VAT is not included in the receipt item price. |
Payment request example with fiscalization object
{
"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": "Merchant's fiscalization identifier",
"positions": [
{
"name": "Product name",
"type": "service",
"amount": 100,
"quantity": 1.0,
"measure_unit_code": 796,
"description": "Product description",
"untaxed": false,
"nomenclature_code": "Product nomenclature code",
"taxes": [
{
"id": "Tax identifier",
"percent": "12",
"type": "vat",
"description": "Tax description",
"inclusive": true
}
]
},
{
"name": "Product name2",
"type": "service",
"amount": 100,
"quantity": 1.0,
"measure_unit_code": 796,
"description": "Product description",
"untaxed": true,
"nomenclature_code": "Product nomenclature code"
}
]
}
}
}
Response
Parameter | Type | Description |
---|---|---|
fiscalization | object | Fiscalization parameters. |
type | string | Transaction type. Possible values: payment , refund , payout . |
id | string (36) | Transaction id in bePaid system. |
external_id | string (255) | Transaction id in the merchant's system |
status * required |
string (255) | Fiscalization transaction status. Possible values: successful - successfully processed; failed - transaction processing error in the provider's system; pending (or incomplete ) - transaction is being processed; error (or expired or deleted ) - transaction processing error in the bePaid system. |
code * required |
string (6) | Fiscalization transaction result code. |
message * required |
string (255) | Fiscalization transaction result message for the merchant. |
friendly_message * required |
string (255) | Fiscalization transaction result message for the customer (only in API v.3). |
receipts *required |
array | Array of receipts. |
id | string (255) | Unique receipt identifier in the system of bePaid. |
serial_id | string (255) | Receipt sequence number in the cash register. |
receipt_num | string (255) | Receipt number in bePaid system. |
created_at | string | Time and date of the receipt creation in bePaid system. Set in the ISO-8601 format: YYYY-MM-DDThh:mm:ssTZD , where YYYY – year (for example, 2019), MM – month (for example, 02), DD – day (for example, 09), hh – hours (for example, 18), mm – minutes (for example, 20), ss – seconds (for example, 45), TZD – time zone (+hh:mm or –hh:mm indicating an offset from UTC). |
ofd_id | string (255) | Unique identifier of the fiscal receipt in OFD system (Operator of Fiscal Data). |
ofd_link | string (1024) | Fiscal receipt URL. |
ofd_qr_code | string (1024) | QR code linking to the fiscal receipt. |
total_amount | integer | Receipt amount in minimal currency units. |
receipt_info | object | Information from the original response of OFD. |
Successful response example. Financial transaction successfully processed. Fiscalization information received.
{
"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"
}
}
}
Unsuccessful response example. Financial transaction successful. Fiscalization service transaction error.
{
"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": "Total amount of items in the receipts not equal to the amount of the transaction. Failed to complete the transaction. Check the request parameters.",
"friendly_message": "Total amount of items in the receipts not equal to the amount of the transaction. Failed to complete the transaction. Contact the merchant for details.",
"receipts": []
},
"credit_card": {
"holder": "John Doe",
"stamp": "3709786942408b7701",
"token": "40bd001563085fc35165329e",
"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": "The operation was successfully processed.",
"gateway_id": 317,
"billing_descriptor": "TEST GATEWAY BILLING DESCRIPTOR",
"status": "successful"
}
}
}
Unsuccessful response example. Financial transaction failed, fiscalization information not sent.
{
"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"
}
}
}
Successful response example. Financial transaction successfully processed. Fiscalization information received.
{
"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": "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"
}
}
]
}
}
Unsuccessful response example. Financial transaction successful. Fiscalization service transaction error.
{
"status": "success",
"code": "S.0000",
"message": "successfully",
"friendly_message": "successfully",
"type": "payment",
"amount": 10000,
"id": "string 255",
"fiscalization": {
"id": "string 36",
"external_id": "string 255",
"status": "failed",
"code": "S.8025",
"message": "Total amount of items in the receipts not equal to the amount of the transaction. Failed to complete the transaction. Check the request parameters.",
"friendly_message": "Total amount of items in the receiptis not equal to the amount of the transaction. Failed to complete the transaction. Contact the merchant for details.",
"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"
}
}
]
}
}
Unsuccessful response example. Financial transaction failed, fiscalization information not sent.
{
"status": "success",
"code": "F.0003",
"message": "Card expired: Ask the customer to use a valid card.",
"friendly_message": "Card expired: Failed to complete the transaction. Use a valid card.",
"type": "payment",
"amount": 10000,
"id": "string 255",
}
Refunds
Refunds with fiscalization are available for payment and capture transactions. The refunds can be made with an API request or in the merchant back office.
Info
Refunds with fiscalization are only available for the full amount of the original (parent) transaction.
Refunds with API
To initiate a refund with fiscalization, include fiscalization
parameter set to true
in the standard refund request.
Example of a refund request with fiscalization
{
"request": {
"amount": 10,
"parent_uid": "ec331643-d17f-4e3c-9a13-b15191e28193",
"reason": "Client request",
"fiscalization": true
}
}
Refunds in the merchant back office
Refunds can also be initiated in the merchant's back office on the Transaction details page. Follow the steps below to make a refund:
1) Find the transaction for which you need to make a refund on Orders page.

2) Click Refund

3) In the displayed modal window,submit the refund amount, enter the reason for the refund and select through the fiscalization service. The refund will be made for the full amount of the parent transaction regardless of the specified amount.

4) The information on the refund along with the associated fiscalization data will be displayed on the transaction details page for the refund and the corresponding original transaction.
