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 in the financial transaction requests.
The following card transactions support fiscalization:
- payment;
- refund;
- capture.
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": "2025"
},
"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": 2024,
"token_provider": "apple_pay" // if Apple Pay transaction, otherwise `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"
}
}
}
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": 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"
}
}
}
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": 2023,
"token_provider": "apple_pay" // if Apple Pay transaction, otherwise `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"
}
}
}
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",
}