Skip to content

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.

Payments

2) Click Refund

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.

Refund with fiscalization

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.

Refund details