CloudKassir for Developers (English) NAV Navbar
Example

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

Online Register

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

cash_registers

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:

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.

Code Operator's name
PeterService LLC "PS ST"
FirstOfd First OFD
Taxcom Taxcom
PlatformaOfd Platforma OFD
OfdYa OfdYa
OfdYandex Yandex OFD
Garantexpress Garant OFD
OfdAstralNalog Astral OFD
Sbis Company "TENZOR", Ltd.

Terms and Conditions of Online-Receipt Generation

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 .

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. The system stores only successful query results.

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:

Parameter Type Use Description
Inn String Required TIN of the organization or individual entrepreneur
DeviceNumber String Required Factory number of the register
FiscalNumber String Required Fiscal storage number
RegNumber String Required Registration number of the register
Url String Required Website address.
Ofd String Required Fiscal Data Operator, see the reference
TaxationSystem Array Required Оne or a few values of taxation systms, see the reference
MerchantEmail String Required Email of the Online Store
MerchantPhone String Optional Phone of the Online Store
IsBso Bool Optional if receipt is a form of strict accountability (BSO)

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:

Parameter Type Use Description
Inn String Required TIN of the organization or individual entrepreneur
Type String Required Payment sign, see the reference
CustomerReceipt JSON Required Receipt composition. See below the parameters table
InvoiceId String Optional Invoice or Order ID in your system
AccountId String Optional Payer's ID in your system

Online Receipt Parameters

Name Parameters
Taxation options see the reference
VAT rate see the reference
Calculation methods see the reference
Calculation objects see the reference
Agent sign see the reference
Agent data see the reference
Purveyor data see the reference

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 calculation method
                "object": 0, // tag-1212 sign of the calculation object - sign of the calculation object, work, service, payment, payout, or another calculation 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 calculation method
                "object": 0, // tag-1212 sign of the calculation object - sign of the calculation object, work, service, payment, payout, or another calculation 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
            }, {
                "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 calculation method
                    "object": 0, // tag-1212 sign of the calculation object - sign of the calculation object, work, service, payment, payout, or another calculation 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", //calculation 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": 6, // 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:

{"Success":true,"Message":"Queued", Model:{Id:"M83loSk"}}

Response example: incorrect:

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

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

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.

Receipt Status Request

Method of getting the receipt status

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

Parameters:

Parameter Type Use Description
Id String Required Receipt ID

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:

Parameter Type Use Description
Id String Required Receipt ID

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:

Parameter Type Use Description
Inn String Required TIN of the organization or individual entrepreneur
DeviceNumber String Required Factory Device Number
FiscalNumber String Required Fiscal Storage Number
OnMaintenance Bool Required True if the register must be placed for maintenance

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:

Parameter Type Use Description
DeviceNumber String Required Factory Device Number
FiscalNumber String Required Fiscal Storage Number

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:

Parameter Format Use Description
Id String Required Receipt unique identifier
DocumentNumber Numeric Required Receipt number
SessionNumber Numeric Required Shift number
Number Numeric Required Receipt number in the shift
FiscalSign String Required Fiscal sign of the document
DeviceNumber Numeric Required Serial number of the cash register
RegNumber String Required Registration number of the cash register
FiscalNumber String Required Fiscal storage number
Inn Number Required TIN
Type String Required Accounting operation type see reference
Ofd String Required Fiscal data operator name
Url String Required URL address of receipt
QrCodeUrl String Required URL address with a QR code for checking a receipt in the Federal Tax Authority
TransactionId Numeric Optional System's transaction number
Amount Number Required Receipt amount
DateTime yyyy-MM-dd HH:mm:ss Required Date/time of receipt generation time in the UTC time zone
InvoiceId String Optional Order or Invoice number
AccountId String Optional Payer's ID
Receipt JSON Required Receipt composition
CalculationPlace String Optional Calculation Place
CashierName String Optional Cashier Name
SettlePlace String Optional Cash Register settle place

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:

Code Value
0 Receipt registered

Kkt

Performed once the online cash register switched to fiscal mode and contains the data of the registration report. Using this notification makes sense if you have dozens or hundreds of cash registers. For other cases, it is easier to obtain the necessary information through Back Office.

Parameters are in the body of request, listed below:

Parameter Format Use Description
Inn String Required TIN of the organization or individual entrepreneur
DeviceNumber String Required Cash register serial number
FiscalNumber String Required Fiscal storage number
RegNumber String Required Registration number of online-cash register
Status String Required Current status: Fiscalized
DocumentNumber String Required Fiscal document number
FiscalSign String Required Fiscal sign of the document
Date Date/Time Required Date and time of registration in format yyyy-MM-dd HH:mm:ss

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:

Code Value
0 Status registered

Notification Validation

All the notifications have a HTTP header Content-HMAC which contains a validation value of the request, calculated using the algorithm HMAC. 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:

HMAC calculation Examples in different programming languages.

The system sends notifications from following addresses: 130.193.70.192 and 185.98.85.109.


Reference

Receipt Types and Settlement Signs

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

Type Settlement sign Use
Income Income Issued upon receiving of funds from a buyer (client)
IncomeReturn Income Return Issued when funds, that previously was received, returned to a buyer (client)
Expense Expense Issued when granting funds to a buyer (client)
ExpenseReturn Expense Return Issued when receiving funds,that previously was given, from a buyer (client)

Taxation Systems

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

Code Taxation System
0 General taxation system
1 Simplified Tax System (Income)
2 Simplified taxation system (Income minus Expense)
3 A single tax on imputed income
4 Single agricultural tax
5 Patent taxation system

VAT values

Code Description
null or not specified no VAT
0 VAT 0%
10 VAT 10%
20 VAT 20%
110 estimated VAT 10/110
120 estimated VAT 20/120

Calculation Methods

Code Description Comment
0 Unknown unknown calculation method
1 FullPrepayment Prepayment 100%
2 PartialPrepayment -
3 AdvancePay Prepaid expense
4 FullPay FullPayment
5 PartialPayAndCredit Partial payment and credit
6 Credit Giving in credit
7 CreditPayment -

Calculation Objects

Code Description
0 Unknown
1 Commodity
2 ExcisedCommodity
3 Job
4 Service
5 GamblingBet
6 GamblingWin
7 LotteryTicket
8 LotteryWin
9 RidAccess
10 Payment
11 AgentReward
12 Composite
13 Another

AgentSign. OFD Tag 1057, 1222

For the correct generation of online-receipt you need: In each heading, specify agent data (Tag 1223) and supplier data (Tag 1224). To transfer not more than 5 such items per one online-receipt (technical limitation of the online-cash register).

Code Description
0 "Bank payment agent", Provision of services by the user, which is a bank payment agent
1 "Bank payment subagent", Provision of services by the user, which is a bank payment subagent
2 "Paying agent", the provision of services by the user, who is a payment agent
3 "Payment subagent", Provision of services by the user, which is a payment subagent
4 "Attorney", Provision of services by the user who is an attorney
5 "Commissioner", the provision of services by the user, who is the commissioner
6 "Agent", Provision of services by a user who is an agent and is not a bank payment agent (subagent), payment agent (subagent), attorney, commission agent

AgentData. OFD Tag 1223

Parameter Type Description
AgentOperationName String The name of the operation of the bank payment agent or bank payment subagent, OFD Tag 1044
PaymentAgentPhone String Payment agent phone, OFD Tag 1073
PaymentReceiverOperatorPhone String Phone of taking payment operator, OFD Tag 1074
TransferOperatorPhone String Phone of money transfer operator, OFD Tag 1075
TransferOperatorName String The name of money transfer operator, ODF Tag 1026
TransferOperatorAddress String Address of money transfer operator, OFD Tag 1005
TransferOperatorInn String TIN of the money transfer operator, OFD Tag 1016

PurveyorData. OFD Tag 1224

Parameter Type Description
Phone String Supplier's phone number, OFD Tag 1171
Name String Supplier's Name, OFD Tag 1225
Inn String Supplier's TIN, OFD Tag 1226

Timezone Codes

The table below contains time zone codes for time conversion.

Code Description
HST (UTC-10:00) Hawaii
AKST (UTC-09:00) Alaska
PST (UTC-08:00) Pacific Time (US and Canada)
MST (UTC-07:00) Mountain time (USA and Canada)
CST (UTC-06:00) Central time (USA and Canada)
EST (UTC-05:00) Eastern time (USA and Canada)
AST (UTC-04:00) Atlantic Time (Canada)
BRT (UTC-03:00) Brazil
UTC (UTC) UTC Format
GMT (UTC) Dublin, Lisbon, London, Edinburgh
CET (UTC+01:00) Amsterdam, Berlin, Bern, Vienna, Rome, Stockholm
CET (UTC+01:00) Belgrade, Bratislava, Budapest, Ljubljana, Prague
CET (UTC+01:00) Brussels, Copenhagen, Madrid, Paris
CET (UTC+01:00) Warsaw, Zagreb, Sarajevo, Skopje
EET (UTC+02:00) Athens, Bucharest
EET (UTC+02:00) Vilnius, Kiev, Riga, Sofia, Tallinn, Helsinki
EET (UTC+02:00) Eastern Europe
EET (UTC+02:00) Kaliningrad (RTZ 1)
MSK (UTC+03:00) Volgograd, Moscow, St. Petersburg (RTZ 2)
MSK (UTC+03:00) Minsk
AZT (UTC+04:00) Baku
AMT (UTC+04:00) Yerevan
SAMT (UTC+04:00) Izhevsk, Samara (RTZ 3)
GET (UTC+04:00) Tbilisi
TJT (UTC+05:00) Ashgabat, Tashkent
YEKT (UTC+05:00) Yekaterinburg (RTZ 4)
ALMT (UTC+06:00) Astana, Almaty
NOVT (UTC+06:00) Novosibirsk (RTZ 5)
KRAT (UTC+07:00) Krasnoyarsk (RTZ 6)
HKT (UTC+08:00) Hong Kong, Beijing, Urumqi, Chongqing
IRKT (UTC+08:00) Irkutsk (RTZ 7)
SGT (UTC+08:00) Kuala Lumpur, Singapore
ULAT (UTC+08:00) Ulaanbaatar
YAKT (UTC+09:00) Yakutsk (RTZ 8)
VLAT (UTC+10:00) Vladivostok, Magadan (RTZ 9)
SAKT (UTC+11:00) Chokurdah (RTZ 10)
ANAT (UTC+12:00) Anadyr, Petropavlovsk-Kamchatsky (RTZ 11)

Notification Types

The table below contains the types of notifications.

Code Name
Receipt Receipt
Kkt Kkt

Error Codes

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

Code Description
-1 Unknown
2 Cash register for this organisation is missing
3 The transferred taxation system is not set in any cash register for this organization
4 Some of required agent data is missing
5 Vendor TIN or vendor phone number for agent settlement is missing
6 Registration of services is not allowed during the registration of a cash register or the buyer's phone number is not correct
7 Incorrect provider's TIN format
8 Document storage resource has been exhausted (Fiscal drive is full)