Online Cash Register

Version 3.0, date 15.03.2019

Federal Law №54

Federal Law №54 "On the use of cash registers", as amended on July 3, 2016, prescribes Internet services, when making an electronic payments (including by a bank card), to use cash registers and send online-receipts to a buyer at the time of calculation.

Law Basics

• You must use the cash register of the new type(online) with the fiscal storage (FN) installed.
• It is necessary to have an agreement with the operator of fiscal data (OFD) for the transfer of data from Online Cash Register to the Federal Tax Authorities.
• It is necessary to specify in the online-receipts all the commodity items: name, price, quantity, amount, VAT rate.
• Online Cahs register must be connected to the Internet
• It is necessary to issue a receipt to the buyer directly at the time of payment: for Internet payments using a bank card, send a receipt to an e-mail or phone.
• It is necessary to change the FN in two cases:
  • upon the expiration of its term;
    
  • when the memory is full before the expiration date;
    and keep it for 5 years.
• No need to enter into an agreement with the Cash Register's Service Center.
• There is no need to present a cash register to the inspector of the Federal Tax Service, all the registration actions can be performed remotely in the personal account of the taxpayer on the website of the Federal Tax Service.

Online Register

We use "MicroPay-FAS" and "MicroPay-FS" cash registers with the connection to any operator of fiscal data.

Cost

The cost of online fiscalization and maintenance services can be found on the website CloudKassir and/or clarified with your account manager.

Onboarding Procedure

To activate the online fiscalization service, you need:

• Get a qualified electronic signature to work with the FTS website.
• Register in the personal account of the tax service: — for legal entities — for individual entrepreneurs
• Sign a contract with CloudKassir.
• Integrate CloudKassir with your service.

After signing the contract and paying the bill, you will get a Cash Register and FN number for registration with the Federal Tax Service.

Fiscal Data Operators

The table below shows the fiscal data operators that online cash registers can work with.

Terms and Conditions of Online-Receipt Generation

• The receipt has at least one position;
• In all positions the name is specified;
• Price and amount of a position is not negative;
• The total sum of all items is greater than zero;
• Input line of product name length is not more than 128 characters, longer lines will be truncated;
• This tax system should match one of the options registered in the Cash Register;
• Numeric values are with an accuracy of no more than two decimal places;
• TIN sent, if required in the documentation.

Sending a Receipt to a Buyer

At the choice of a buyer, an online receipt must be sent by e-mail or SMS (Viber / WhatsApp / Telegram) message to the phone number. If online receipt generating request is correct, or you did it manually in Back Office, the system sends all the necessary details in the Receipt notification about generated receipts.

The Moment of Sending a Receipt

A receipt must be sent to the buyer at the time of settlement. For Single message scheme payment, a receipt is generated immediately once the payment has been completed, for dual message scheme payments - upon confirmation of the operation.

Online Receipt Testing

When operating in test mode, cash receipts will be generated in a demo Cash Register with a debug fiscal drive. You can transfer data for an online receipt when paying in test mode and check the operation of the online cash register.

API

Cash Register API is a program interface for interacting with an online cash register.

Interaface works on api.cloudpayments.ru and supports functions for fiscalization of cash registers, as well as the generation of an online receipts and sending them to the customers.

Interface Basics

Selection of format of the parameters to transfer is determined on the client side and is controlled via the request header Content- Type .

• For parameters «key=value» Content-Type: application/x-www-form-urlencode;
  
• For parameters JSON Content-Type: application/json;

System's reply have JSON format, which is as minimum includes two parameters: Success and Message:

{ "Success": false, "Message": "Invalid Amount value" }

The first parameter indicates the result of the query - whether it is successful or not, the second one may contain an additional information.

Requests Authentication

To authenticate the request, use HTTP Basic Auth - send the login and password in the header of HTTP request. Public ID is used as login, API Secret is used as password. Both of these values can be obtained in your account.

API Idempotency

Idempotency - the ability of API to produce the same result as the primary without re-processing in case of duplicated requests. This means that you can send several requests to the system with the same identifier, and only one request will be processed. All the answers will be identical. By this way, protection against network errors is implemented, which lead to the creation of duplicate records and actions.

To enable idempotency, it is necessary in API request to send a header with the key X-Request-ID containing a unique identifier. Generation of the request identifier remains on your side - it can be a guid, a combination of the order number, date and amount, or any other value on your choice. Each new request that needs to be processed must include the new X-Request-ID value. The processed result is stored in the system for 1 hour.

Test Method

To test the interaction with the API, you can call this method.

Method URL:
https://api.cloudpayments.ru/test

Parameters:
none.

Response example:
Method returns a request status.

{"Success":true,"Message":"bd6353c3-0ed6-4a65-946f-083664bf8dbd"}

Register Fiscalization

The method of launching a cash register to the fiscal operation mode (initial registration).

Method URL:
https://api.cloudpayments.ru/kkt/fiscalize

Parameters:

Request example:

{
   "Inn":"7708806062",                      //TIN
   "DeviceNumber":"00000000000000000001",   //Factory number of the register
   "FiscalNumber":"9999078900005430",       //Fiscal storage number
   "RegNumber":"0000000004030311",          //Registration number of the register
   "Url":"www.cloudpayments.ru",            //Website address. 
   "Ofd":"PeterService",                    //Fiscal Data Operator
   "TaxationSystem":[0],                    //Taxation System
   "MerchantEmail":"my@mail.ru",            //Email of the Online Store
   "MerchantPhone":"899999999",             //Phone of  the Online Store 
   "IsBso":false,                           //not BSO
}

Cash register fiscalization is an asynchronous operation, therefore, in response to an API request, the system reports that the command has been queued and will be processed within a few minutes. The registration report will be sent to your e-mail, and in addition, you can enable Kkt notification in your account.

Response example:

{"Success":true,"Message":"Fiscal data queued"}

Online Receipt Generation

Method of an online receipt generation.

Method URL:
https://api.cloudpayments.ru/kkt/receipt

Parameters:

When specifying the e-mail address or phone number of a payer, the system will automatically send an email with the receipt or a message with a link to the receipt. You can also do not specify contacts, but send a receipt to the buyer in electronic form with the indication of the fiscal details received in the Receipt notification.

Type

The table contains the types of receipt and its corresponding settlement characteristics that are used to generation of receipts.

CustomerReceipt

Receipt composition parameters.
CustomerReceipt object also could be transferred within Data either trough widget, or in any other payment method of CloudPayments (for example, payment by cryptogram, by a token, payment confirmation, refunds, subscription changes and so on) for Income online-receipt generation after a successful payment.

Items

Item parameters of receipt.

VAT

Method

Settlement method attribute.

Object

Settlement object attribute.

AgentData

Agent data, OFD Tag 1223.

PurveyorData

Purveyor data, OFD Tag 1224.

TaxationSystem

The table below contains the options for tax systems of legal entities and individual entrepreneurs, which are used in the generation of online-receipts.

AgentSign

Agent Sign attribute, OFD Tag 1057, 1222. For the correct generation of online-receipt you need: In each heading, specify agent data (Tag 1223) and purveyor data (Tag 1224).

Amounts

Total amount of payment or refund. Must contain one of the following parameters

Request example

{
    "Inn": "7708806062", //Tin
    "InvoiceId": "1234567", //Order number, Optional
    "AccountId": "user@example.com", //Payer's ID, Optional
    "Type": "Income", //Payment sign
    "CustomerReceipt":
     {
        "Items": //commodity items
        [
            {
                "label": "Product №1", //goods name
                "price": 100.00, 
                "quantity": 1.00, 
                "amount": 100.00, 
                "vat": 0, //vat rate
                "method": 0, // tag 1214 sign of the settlement method
                "object": 0, // tag 1212 sign of the settlement object - sign of the settlement object, work, service, payment, payout, or another settlement object
                "measurementUnit": "шт" 
            }, 
            {
                "label": "Product №2",  //item's name
                "price": 200.00, 
                "quantity": 2.00, 
                "amount": 300.00, //amount with 25% discount
                "vat": 10, //vat rate
                "method": 0, // tag 1214 sign of the settlement method
                "object": 0, // tag 1212 sign of the settlement object - sign of the settlement object, work, service, payment, payout, or another settlement object
                "measurementUnit": "шт",
                "excise": 0.01, // tag 1229 excise amount
                "countryOriginCode": "156", // tag 1230 digital code of the goods origin country in accordance with the National country classification in 3 characters
                "customsDeclarationNumber": "54180656/1345865/3435625/23", // tag 1231 customs declaration registration number 32 characters
                "ProductCodeData":  //product mark data
                        { 
                        "CodeProductNomenclature":"3031303239303030303033343....a78495a4f6672754744773d3d" //full HEX of marking barcode (Only for Micropay cash registers)
                        }
            }, 
            {
                "label": "Product №3", //item's name
                    "price": 300.00, 
                    "quantity": 3.00,
                    "amount": 900.00, 
                    "vat": 20, //vat rate
                    "method": 0, // tag 1214 sign of the settlement method
                    "object": 0, // tag 1212 sign of the settlement object - sign of the settlement object, work, service, payment, payout, or another settlement object
                    "measurementUnit": "шт", 
                    "AgentSign": 6, // tag OFD 1222
                    "AgentData": //tag OFD 1223
                        { 
                        "AgentOperationName": null, // name of the operation of the bank payment agent or bank payment subagent, tag OFD 1044
                        "PaymentAgentPhone": null,  //  payment agent telephone, tag OFD 1073
                        "PaymentReceiverOperatorPhone": null, // tag OFD 1074
                        "TransferOperatorPhone": null, // tag OFD 1075
                        "TransferOperatorName": null, // tag OFD 1026
                        "TransferOperatorAddress": null, // tag OFD 1005
                        "TransferOperatorInn": null // tag OFD 1016
                        },
                    "PurveyorData": //tag OFD 1224
                        { 
                        "Phone": "+74951234567", // tag OFD 1171
                        "Name": "ООО Ромашка", // tag OFD 1225
                        "Inn": "1234567890" // tag OFD 1226
                        }
            }
        ],
        "calculationPlace": "www.my.ru", //settlement place, by default taken from the cash register
        "taxationSystem": 0, //optional, if you have one taxation system
        "email": "user@example.com", //buyer's e-mail , if you need to send a email with the receip
        "phone": "", //buyer's phone number in free format, if you need to send a link on the receipt via SMS
        "customerInfo": "", // tag 1227 Buyer's organisation name or name, middlename(if available), surname and passport data (of buyer)
        "customerInn": "7708806063", // tag 1228 TIN of the buyer  
        "isBso": false, //if receipt is a form of strict accountability
        "AgentSign": null, // tag OFD 1057
        "amounts":
        {
            "electronic": 1300.00, // the amount of payment by electronic money
            "advancePayment": 0.00, // prepayment amount (offset of advance payment) (2 decimal places)
            "credit": 0.00, // postpay amount (on credit) (2 decimal places)
            "provision": 0.00 // the amount of payment by the reciprocal grant (certificates, other physical values) (2 decimal places)
        }
    }
}

Online Receipt Generation is an asynchronous operation, therefore, in response to an API request, the system reports that the command has been queued and will be processed within a few seconds. To get the operation result you can enable Receipt notification in your account. Once receipt is queued it has a unique ID.

Response example: accepted:

{
    "Model": {
        "Id": "QSnuAqV",
        "ErrorCode": 0
    },
    "InnerResult": null,
    "Success": true,
    "Message": "Queued"
}

Response example: incorrect:

{
    "Model": {
        "ErrorCode": -1
    },
    "InnerResult": null,
    "Success": false,
    "Message": "Компания с ИНН 7777777777 не найдена"
}

In case of failure the Model returns an object ErrorCode field (see the reference)

Receipt Status Request

Method of getting the receipt status

Method URL:
https://api.cloudpayments.ru/kkt/receipt/status/get

Parameters:

Request example:

{ "Id": "Nr9eTaj" }

Response example:

{
   "Model": "Processed",
   "Success": true
}

Receipt Details Request

Method of getting the receipt details

Method URL:
https://api.cloudpayments.ru/kkt/receipt/get

Parameters:

Request example:

{ "Id": "Nr9eTaj" }

Response example:

{
    "Model": {
        "Email": "user@example.com",
        "Phone": null,
        "Items": [
            {
                "Label": "Product №1",
                "Price": 100,
                "Quantity": 1,
                "Amount": 100,
                "Department": null,
                "Vat": 0,
                "EAN13": null,
                "AgentSign": null,
                "Method": 6,
                "Object": 3,
                "MeasurementUnit": "шт",
                "Code": "1322",
                "AgentData": null,
                "PurveyorData": null
            },
            {
                "Label": "Product №2",
                "Price": 220,
                "Quantity": 2.5,
                "Amount": 550,
                "Department": null,
                "Vat": 10,
                "EAN13": null,
                "AgentSign": 2,
                "Method": 0,
                "Object": 0,
                "MeasurementUnit": null,
                "Code": null,
                "AgentData": {
                    "PayingAgentOperation": null,
                    "PayingAgentPhone": null,
                    "ReceivePaymentsOperatorPhone": null,
                    "MoneyTransferOperatorPhone": null,
                    "MoneyTransferOperatorName": null,
                    "MoneyTransferOperatorAddress": null,
                    "MoneyTransferOperatorVATIN": null
                },
                "PurveyorData": null
            },
            {
                "Label": "Product №3",
                "Price": 150,
                "Quantity": 5,
                "Amount": 600,
                "Department": null,
                "Vat": 20,
                "EAN13": null,
                "AgentSign": null,
                "Method": 0,
                "Object": 0,
                "MeasurementUnit": null,
                "Code": null,
                "AgentData": null,
                "PurveyorData": null
            }
        ],
        "TaxationSystem": 2,
        "Amounts": null,
        "IsBso": false,
        "AdditionalData": {
            "Id": "Nr9eTaj",
            "AccountId": "user@example.com"
            "Amount": 1150,
            "CalculationPlace": "www.my.ru",
            "CashierName": "test",
            "DateTime": "2018-11-14T16:19:33",
            "DeviceNumber": "00000000000000000001",
            "DocumentNumber": "1323",
            "FiscalNumber": "9999078900005430",
            "FiscalSign": "13223",
            "InvoiceId": "1322223",
            "Ofd": "Первый ОФД",
            "OfdReceiptUrl": "http://url.com/adress",
            "OrganizationInn": "7708806062",
            "QrCodeUrl": "https://qr.cloudpayments.ru/receipt?q=t%3d20181205T185000%26s%3d99.00%26fn%3d9999078900005430%26i%3d157347%26fp%3d1016954666%26n%3d1",
            "RegNumber": "322223",
            "SenderEmail": "sender@email.com",
            "SessionCheckNumber": "12223",
            "SessionNumber": "1",
            "SettlePlace": "117342, Москва, ул. Бутлерова, 17Б", //address
            "TransactionId": 14442,
            "Type": "Income",
        }
    },
    "InnerResult": null,
    "Success": true,
    "Message": null
}

Cash Register State Change

The method of manual control of the state of the cash register. Cash register can be turned off (for maintenance) and activated (put into operation).

Method URL:
https://api.cloudpayments.ru/kkt/state

Parameters:

Request example:

{
   "Inn":"7708806062",                      //TIN
   "DeviceNumber":"00000000000000000001",   //Factory Device Number
   "FiscalNumber":"9999078900005430",       //Fiscal Storage Number
   "OnMaintenance":true          //Maintenance sign
}

Response example:

{"Success":true,"Message":"Kkt status was changed"}

Receiving Cash Register Data

Method of receiving cash register data.

Method URL:
https://api.cloudpayments.ru/kkt/state/get

Parameters:

Request example:

{
   "DeviceNumber": "00000000000000000001",   //Factory Device Number
   "FiscalNumber": "9999078900005430",       //Fiscal Storage Number
}

Response example:

{
    "Inn":"7708806062", //Tin
    "DeviceNumber": "00000000000000000001", //Factory Device Number
    "FiscalNumber": "9999078900005430", //Fiscal Storage Number
    "RegNumber": "0000000004030311", //Registration number of the register
    "Status": "Online", 
    "Fiscal": true, //Fiscal mode
    "OfdName": "Первый ОФД", //OFD
    "SettlePlace": "117342, Москва, ул. Бутлерова, 17Б", //address/location
    "CalculationPlace": "www.my.ru", 
    "KkmModelName": "Терминал ФА", //Model name of cash register
    "FiscalDateEnd": "2021-01-01T00:00:00.000+000", //Fiscal storage expiration date
    "FirmwareVersion": "14.1.2", //firmware version
    "IsBso": false, //for BSO
}

Notifications

Notification - HTTP request from the system to your site. Similar requests are also called callback or webhook.

Receipt

Performed once online receipt has been generated and sent to payer.

Used to inform about the generated online receipt: the system sends a request to the address of the merchant with the receipt details, and the merchant site have to register the information.

Parameters are in the body of request, listed below:

The system expects to receive a response in JSON format with the required parameter code:

{"code":0}

The code defines the result of notification processing by the merchant and can take only one value:

Interface Basics and Notification Validation

Parameters must be sent by POST or GET method in the body of request by the format “key = value”.

The receipt notification have the X-Content-HMAC and Content-HMAC HTTP headers which contains a validation value of the request, calculated using the algorithm HMAC. The only difference is that the first one is generated from URL decoded (or not encoded) parameters, and the second one is generated from URL encoded parameters (which can cause problems). If you need to verify the authenticity and integrity of notifications, you can calculate the validation value on your side and compare it with what came in the request. The match confirms that the notice was sent from us and came to you in its original form.

When implementing notification validation, pay attention to the following points:

• For notifications sent by POST the message is the request body. For GET — String parameters;
  
• Hash is calculated by function SHA256;
  
• The secret API is used as a key, which can be obtained in your Back Office;
  
• The calculated value is in base64.

HMAC calculation Examples in different programming languages.

The system sends notifications from the following addresses: 130.193.70.192, 185.98.85.109. New address subnets have been added - 91.142.84.0/27, 87.251.91.160/27 and 185.98.81.0/28.

Reference

Timezone Codes

The table below contains time zone codes for time conversion.

Notification Type

The table below contains the type of notifications.

Error Codes

The table below contains the error codes of Online Receipt Generation method.