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.

Transition to PFD 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 right now 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

You can start sending the new data. If you won't send them, Orange Data will add default values on its side.

ModulKassa and Business.ru Online Receipts

You can start sending the new data. Your online sales register can't process it yet but there won't be any issues with payments or receipts.

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 parameters customerContact and taxSystem (optional) are transmitted in the format "key"—"value". 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

{
    "customerContact": "+7900123121212",
    "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"
    }]
}

Parameters for the receipt

Parameter Type Necessity Description

customerContact

string, 64 characters

Mandatory

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 indicated.

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.

items Object Mandatory Products
Product

quantity

Decimal accurate to the thousandth place

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—VAT at the rate of 0%

3—VAT of the receipt at the rate of 10%

4—VAT of the receipt at the rate of 18%

5—VAT of the receipt at the applicable rate of 10/110

6—VAT of the receipt at the applicable rate of 18/118.

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 Vu\", 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;

  • 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.

Explanations

Buyer's contact details

  • The customerContact field is mandatory. In this field, you need to transmit syntactically correct phone number or email address. If the field is empty or contains incorrect data, the payment won't come through.
  • 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