Setting up software-based cash register

How to set up SBCR

Register your cash register with our SBCR service provider
Available SBCR services
Currently, the only available service is Cash Desk
Add new parameters to API request

In addition to the standard set of parameters for payment requests, it is required to include product data for all payments and refunds (purchase, auth, capture, and refund transactions).

Parameter	Type	Required	Description
`products.id`	UUID	✅	Unique product identifier
`products.name`	String	✅	Product name
`products.amount`	Number	✅	Price per unit of goods/work/service
`products.qty`	Number	✅	Quantity (total payment amount = `products.qty` * `products.amount`)
`products.unit`	String	✅	Unit of measurement (allowed values are kg, m, pc, l)
`products.bar_code`	String		Product barcode (optional for fiscalization but mandatory for the "National cashback" program)
`customer_email`	String		Customer’s email. Required if `products.fiscalReceiptDelivery = “email”`
`customer_phone`	String		Customer mobile phone. Required if `products.fiscalReceiptDelivery = “viber” or “sms”`
`products.taxes.type`	String		Type of tax (allowed values are vat, non-vat). If the business entity is not a VAT payer, the value `non-vat` must be provided.
`products.taxes.prc`	Number		Tax rate % (valid values: 0, 7, 14, 20)
`products.fiscalReceiptDelivery`	String	✅	Specifies the method by which the fiscal receipt will be delivered to the customer. Allowed values: `email, viber, sms, none`. Depending on the passed value, either the customer_phone or customer_email parameter is required.

caution

When using the payment widget, different fiscalization parameters need to be used.

Example of Body request:

{
  "pos_id": "00000000-0000-0000-0000-000000000000",
  "mode": "direct",
  "method": "purchase",
  "amount": 100,
  "currency": "UAH",
  "cc_number": "4111111111111111",
  "exp_month": 12,
  "exp_year": 24,
  "card_cvv": "123",
  "order_id": "123456789",
  "description":"Опис товару",
  "payway": "cc",
  "order_3ds_bypass": "supported",
  "customer_email": "[email protected]",
  "customer_phone": "+38(066) 123-45-67",
  "products": [{
    "id": "1",
    "name": "product name",
    "unit": "pc",
    "bar_code":"4876534567183",
    "amount": 50,
    "taxes": [{"type":"vat", "prc": 20}],
    "qty": 2,
    "fiscalReceiptDelivery": "email"
  }],
  "server_url": "http://callback-stub:9000/consume"
}

In case of an error in one of the parameters responsible for the product data, the response will include an error message with information about the specific field that contains the invalid value.

Example of such a response:

{
    "message": "Invalid products provided",
    "args": [
        {
            "field_name": "products[0].name",
            "violation": "..."
        },
        {
            "field_name": "products[0].unit",
            "violation": "..."
        },
        {
            "field_name": "products[1].name",
            "violation": "..."
        },
        {
            "field_name": "products[1].unit",
            "violation": "..."
        },
        {
            "field_name": "products[0].id",
            "violation": "..."
        },
        {
            "field_name": "products[1].id",
            "violation": "..."
        },
        {
            "field_name": "products",
            "violation": "..."
        }
    ]
}

caution

Prior to proceeding to the next step, it is imperative to make the above-mentioned changes to the API integration. Failure to introduce the necessary changes while setting up the SBCR will result in transaction failures due to missing mandatory parameters.

Set up SBCR in merchant portal

Open the general settings of the merchant account and select the SBCR option.
Click the New Configuration button.
Fill out the form:
- Configuration name: any value of your choice.
- Service provider: the provider of the SBCR service you register your cash register with (currently, only Cash Desk is available).
- Cash register identifier (SBCR ID):
  An example value of the Cash Desk parameters "num_fiscal": “100000000000”
- API token from the SBCR service provider:
  An example value of the Cash Desk parameters “api_token” : "00000000-0000-0000-0000-000000000000
- Scope of application: select a required legal entity or private entrepreneur
- Enable the application of SBCRs for payments switcher as it is shown in the image below.
Check the entered data and submit the form.
After submitting the form the SBCR application will be enabled for the corresponding configuration.
Add a Digital Signature (DS) for signing fiscal receipts of the respective business entity.
- In the SBCR section, select the Digital signatures tab.
- Choose the option "Add digital signatures".
- Enter the desired name for the DS and the business entity it belongs to.
- Upload the key file and enter its password.
- Confirm the upload by clicking the "Submit" button.

SBCR

After this, subsequent fiscal receipts of the respective business entity will be signed with the uploaded key until it is replaced or deleted, or until its expiration date.

info

If you do not utilize the merchant portal, please reach out to your account manager or our support team at [email protected] to enable the SBCR feature.

Obtaining fiscal receipts

Working with fiscal receipts can be done in the following ways:

Sending fiscal receipts to the payer.
Retrieving a URL link to the fiscal receipt via an API request.

Sending fiscal receipts to the payer

Fiscal receipts can be sent to the payer through a SBCR provider in one of the following ways:

By email (default option).
Via SMS.
Through a Viber message.

caution

Sending via SMS or Viber is a paid service and is charged according to the SBCR provider CashDesk’s terms: https://cashdesk.ua/prices

To set one of the specified methods for sending a fiscal receipt to the payer, the request for Purchase, Capture, or Refund must additionally include the following parameter:

Parameter	Type	Required	Description
`f_receipt_delivery`	String		Fiscal receipt delivery option

For sending via Email:

Value: email.
The payment request must include the payer’s email address (customer_email). If customer_email is not provided, the fiscal receipt will not be sent to the payer.

For sending via SMS:

Value: sms.
The payment request must include the payer’s phone number (customer_phone). If customer_phone is not provided, the fiscal receipt will be sent via email if an email address was provided.

For sending via Viber:

Value: viber.
The payment request must include the payer’s phone number (customer_phone). If customer_phone is not provided, the fiscal receipt will be sent via email if an email address was provided.

If the f_receipt_delivery parameter is set to none, the fiscal receipt will not be sent to the payer.

info

If the f_receipt_delivery parameter is not included in the request or contains a non-standard value, the receipt will default to being sent via email.

Obtaining a URL Link to the fiscal receipt via an API request

You can also receive a URL link to the fiscal receipt in the response to a request for re-polling the status of a finalized transaction.

Since there is a time delay between processing the transaction on the Tranzzo side and the completion of fiscalization on the tax authorities’ side, we recommend sending a request to re-poll the status of the finalized transaction at least 30 seconds after receiving a callback indicating success.

In the response to the request, among other parameters, you will receive:

{
…
"fiscal_receipt_url": "https://url.com/2fga245-3f12-4c88-8e0b-a54231abcdf9a/pdf",
…
}

How to set up SBCR​

Register your cash register with our SBCR service provider​

Add new parameters to API request​

Set up SBCR in merchant portal

Obtaining fiscal receipts​

How to set up SBCR

Register your cash register with our SBCR service provider

Add new parameters to API request

Obtaining fiscal receipts