Parameters for creating a receipt

Attention. This is an old version of the API. Switch to the Yandex.Checkout API.

The parameters for transmitting fiscal data are added to a usual payment form. Their transmission is required if you set up interaction with your online sales register via Yandex.Checkout (start using an online sales register from one of our partners and configure it accordingly in the dashboard, see Changes in the protocol for working under Federal Law No.54 (54-FZ)).

One additional parameter, ym_merchant_receipt, is added to the form and contains all required data.

Changes in receipts from 1 July 2019

On 1 July 2019, new amendments to Federal Law No. 54-FZ have entered into force. Now, in some cases you will need to send additional information about the user and the product to Yandex.Checkout.

User information

You can send additional information about the user (customer):

  • user's name (tag 1227) — fullName;
  • user's INN (TIN) (tag 1228) — inn.

Online sales registers that support the new settings: Orange Data, ATOL Online.

Attention. The customerContact parameter is deprecated: you can still use it, but we recommend sending the phone number and the email address in the customer parameter.
Additional information about the product

For each product, (items) you can send:

  • product code (tag 1162) — productCode;
  • code of the product's country of origin (tag 1230) — countryOfOriginCode;
  • number of the customs declaration (tag 1231) — customsDeclarationNumber;
  • product's excise (tag 1229) — excise.

Online sales registers that support the new settings: Orange Data, ATOL Online (product code only).

Transition to FFD 1.05

A new fiscal data format (FFD 1.05) will be adopted on 1 January 2019. It requires the inclusion of additional parameters:
  • payment subject attribute (paymentSubjectType);
  • payment method attribute (paymentMethodType).

These parameters are optional in the protocol. In 2019, they become mandatory for the Tax Service, but at this time the processing methods vary between online sales registers.

ATOL Online

To send new parameters, change the settings on the ATOL's side. How to do it:

  1. First, configure the process of sending additional parameters using our protocol.
  2. Then log in to your ATOL dashboard and switch to the new fiscal data format.

Correct order is crucial: if you switch to the new format on ATOL's side before you start sending the new data, the payments or receipts will not be properly processed.

Orange Data, ModulKassa, and Business.Ru Online Receipts

You can start sending the new data. If you won't send them, your online sales register will add default values on its side.

Additional parameter for the receipt

Parameter Type Description

ym_merchant_receipt

string

Details for creating a receipt in the JSON format.

Format of the details for the receipt

Details for the receipt are transmitted in the JSON format. The customer and taxSystem (optional) parameters are sent in the "key"—"value" format. With these parameters, an array of products, which include products and their description, is transmitted. The product description is transmitted as one object; separate object is created for each product.

Example of details in the JSON format

{
    "customer": {
        "email": "johndoe@yandex.ru"
    },
    "taxSystem": 1,
    "items": [{
        "quantity": 1.154,
        "price": {
            "amount": 300.23
        },
        "tax": 3,
        "text": "Green tea \"Yun Woo\", kg",
        "paymentMethodType": "full_prepayment ",
        "paymentSubjectType": "commodity"
    }, 
    {
        "quantity": 2,
        "price": {
            "amount": 200.00
        },
        "tax": 3,
        "text": "Tea cup, pcs., 10% discount",
        "paymentMethodType": "full_prepayment",
        "paymentSubjectType": "commodity"
    }]
}

Parameters for the receipt

Parameter Type Necessity Description

customerContact

string, 64 characters

Optional
Attention. The customerContact parameter is now deprecated. You can still use it but we recommend sending the data in the customer parameter.

Buyer's phone number or email address.

Restrictions:

  • phone number in the format +79210000000 or email address (we check it);
  • you should only transmit one piece of information: either email address or phone number;
  • you should not transmit several email addresses or phone numbers.

taxSystem

int

Optional

Store's Tax System (STS). The parameter is only required if you use several tax systems. Otherwise, the parameter is not transmitted.

Possible values — a number from 1 to 6:

1 — general tax system;

2 — simplified tax system (income);

3 — simplified tax system (income less expenses);

4 — unified imputed income tax;

5 — unified agricultural tax;

6 — patent tax system.

Important: products with different taxSystem must be transmitted in different receipts.

customer

Object

Optional

User information.

See Parameters of nested objects — customer

items Object Mandatory

Products

See Parameters of nested objects — items

Parameters of nested objects

Parameter Type Necessity Description
User (customer)

fullName

string, maximum of 256 characters

Optional

For legal entities—company name, for sole proprietors and individuals—full name. If an individual does not have an INN (TIN), this parameter should include passport information.

inn

string

Optional

User's INN (TIN) (10 or 12 digits). If an individual does not have an INN (TIN), the customer.fullName parameter should contain passport information.

email

string

Required if phone or customerContact are not specified.

User's email address for sending the receipt.

phone

string

Required if email or customerContact are not specified.

User's phone number for sending the receipt. Set in the ITU-T E.164 format, for example, +79000000000.

Product (items)

quantity

Decimal accurate to the thousandth place. Maximum possible value depends on the model of your online sales register

Mandatory

Product quantity. Defines the quantity of products in the order or quantity of products sold by weight.

price

Object

Mandatory

Product price.

amount

CurrencyAmount (decimal accurate to the hundredths place)

Mandatory

Price per unit.

currency

CurrencyCode

Optional

Currency code: RUB (Russian ruble).

tax

int

Mandatory

VAT rate. Possible values — a number from 1 to 6:

1 — without VAT;

2 — 0% VAT rate;

3 — 10% VAT rate;

4 — 20% VAT rate;

5 — VAT rate 10/110;

6 — VAT rate 20/120.

text

string, 128 characters

Cyrillic or Roman alphabet

Mandatory

Product name.

Restrictions:

  • Special characters (for instance, quotes) should be introduced in accordance with the JSON data format. For instance: "text": "Green tea \ "yun woo\", kg"
paymentSubjectType string, 128 characters Optional Payment subject attribute is the product's category for the Tax Service.
Possible values:
  • commodity — product;

  • excise — excise goods;

  • job — job;

  • service — service;

  • gambling_bet — a bet in gambling;

  • gambling_prize — gambling winnings;

  • lottery — lottery ticket;

  • lottery_prize — lottery winnigs;

  • intellectual_activity — intellectual property;

  • payment — payment;

  • agent_commission — agent's commission;

  • property_right — property rights;

  • non_operating_gain — non-operating income;

  • insurance_premium — insurance fee;

  • sales_tax — sales tax;

  • resort_fee — resort fee;

  • composite — several subjects;

  • another — other.

paymentMethodType string, 128 characters Optional Payment method attribute is the payment method's category for the Tax Service.
Possible values:
  • full_prepayment — full prepayment;

  • partial_prepayment — partial prepayment;

  • advance — advance payment;

  • full_payment — full payment;

  • partial_payment — partial payment and loan;

  • credit — loan;

  • credit_payment — loan repayment.

productCode string Required parameter if the product is to be marked

Product code is a unique number assigned to a unit of product during marking.

Format: a hexadecimal number with spaces. Maximum length is 32 bytes. Example: 00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00.

countryOfOriginCode string Optional

Country of origin code in accordance with the national Russian classifier of world countries (OК (MК (ИСО 3166) 004-97) 025-2001). Example: RU.

customsDeclarationNumber string, 1 to 32 characters Optional

Number of the customs declaration.

excise string, decimal accurate to the hundredths place Optional

The amount of excise tax for the goods including kopeks.

Explanations

Buyer's contact details

  • In order for the payment to be processed, you'll need to send the user's contact information for creating a receipt: a syntactically correct phone number or email address. This information must be included in the customer object or in the customerContact parameter.
    Attention. The customerContact parameter is now deprecated. You can still use it but we recommend sending the data in the customer object.
  • Fiscal Data Operator (OFD) transmits the receipt to the buyer (conditions of this transmitting depend on your OFD). The receipts are sent to mobile phone numbers of Russian carriers (they all begin with +7). The receipt may fail to be delivered to a non-Russian mobile phone number.

Product quantity, weight, price

  • The amount field should contain a price for one piece of the product; the quantity field should contain the quantity of the products. If the amount field contains a price for one piece of the product, you need to transmit number of pieces (quantity=2, for instance, two pies of one kind). If the amount field contains a price for one kilogram of the product, you need to transmit the product's weight (quantity=1.253, for instance, a pie that weights 1 kg 253 g).
  • The specified price should be free of taxes.
  • Total amount you transmit to ym_merchant_receipt, should match the sum. If they do not match, the receipt won't be created, and the payment might fail.
  • You can transmit up to 100 products to ym_merchant_receipt. This means not more than 100 such blocks : {"quantity": 1.154,"price": {"amount": 300.23},"tax": 3,"text": "Product A"}
  • You can add information about a discount or payment in advance to the product's name. For instance: "text": "30% advance payment, tabletop game \"Tea Time\""}

Example of a payment form with parameters for the receipt

<form action="https://money.yandex.ru/eshop.xml" method="post">
        <input name="shopId" value="1234" type="hidden"/>
        <input name="scid" value="4321" type="hidden"/>
        <input name="sum" value="746.47" type="hidden">
        <input name="customerNumber" value="abc000" type="hidden"/>
        <input name="paymentType" value="AC" type="hidden"/>
        <input name="orderNumber" value="abc1111111" type="hidden"/>
        <input name="cps_phone" value="+79123456543" type="hidden"/>
        <input name="cps_email" value="user@domain.com" type="hidden"/>
        <input name="ym_merchant_receipt" value='{"customerContact": "+79001231212","taxSystem": 1, "items":[{"quantity": 1.154, "price": {"amount": 300.23},  "tax": 3,"text": "Green tea \"Yun Vu\", kg","paymentMethodType": "full_prepayment ","paymentSubjectType": "commodity"},{"quantity": 2, "price": {"amount": 200.00},  "tax": 3,"text": "Tea cup, pcs, 10% discount","paymentMethodType": "full_prepayment ","paymentSubjectType": "commodity"}]}'
        type="hidden"/>
        <input type="submit" value="Pay"/>
        </form>

See also

Changes in the protocol for working under Federal Law No.54 (54-FZ)

Sending details for the receipt