Parameters for creating a receipt — [Archive] Payment solution protocol for merchants

Parameters for creating a receipt

This is an old version of the API. Switch to the YooMoney 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 YooMoney (start using an online sales register from one of our partners and configure it accordingly in the dashboard, see Payments by 54-FZ).

One additional parameter, ym_merchant_receipt (string type), is added to the form and contains all required data 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

JSON
{
    "customer": {
        "email": "user@example.com"
    },
    "taxSystem": 1,
    "items": [{
        "quantity": 1.154,
        "price": {
            "amount": 300.23
        },
        "tax": 3,
        "text": "Green tea \"Yun Wu\", kg",
        "paymentMethodType": "full_prepayment ",
        "paymentSubjectType": "commodity"
    },
    {
        "quantity": 2,
        "price": {
            "amount": 200.00
        },
        "tax": 3,
        "text": "Teacup, unit, 10% discount",
        "paymentMethodType": "full_prepayment",
        "paymentSubjectType": "commodity"
    }]
}

Parameters for the receipt

Parameter	Type	Description
customer	Object	User information. See Parameters of nested objects — customer Required if `customerContact` is not specified.
customerContact	string, 64 characters	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. Required if `customer` is not specified.
taxSystem	int	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. Optional
items	Object	Products See Parameters of nested objects — items Required

Parameters of nested objects

Parameter	Type	Description
User (customer)
fullName	string, maximum of 256 characters	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. Optional Online sales register that support this parameter: Orange Data, ATOL Online.
inn	string	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. Optional Online sales register that support this parameter: Orange Data, ATOL Online.
email	string	User’s email address for sending the receipt. Required if `phone` or `customerContact` are not specified.
phone	string	User’s phone number for sending the receipt. Set in the ITU-T E.164 format, for example, `+79000000000`. Required if `email` or `customerContact` are not specified.
Product (items)
quantity	Decimal. Maximum possible value and maximum number of digits after the decimal point depend on the model of your online sales register	Product quantity. Defines the quantity of products in the order or quantity of products sold by weight. Required
price	Object	Product price. Required
amount	CurrencyAmount (decimal accurate to the hundredths place)	Price per unit. Required
currency	CurrencyCode	Currency code: `RUB` (Russian ruble). Optional
tax	int	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. Required
text	string, 128 characters Cyrillic or Roman alphabet	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"` Required
paymentSubjectType	string, 128 characters	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 winnings; `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. Optional
paymentMethodType	string, 128 characters	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. Optional
productCode	string	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`. Required parameter if the product is to be marked. Online sales register that support this parameter: Orange Data, ATOL Online.
countryOfOriginCode	string	Country of origin code in accordance with the national Russian classifier of world countries (OК (MК (ИСО 3166) 004-97) 025-2001). Example: `RU`. Optional Online sales register that support this parameter: Orange Data.
customsDeclarationNumber	string, 1 to 32 characters	Number of the customs declaration. Optional Online sales register that support this parameter: Orange Data.
excise	string, decimal accurate to the hundredths place	The amount of excise tax for the goods including kopeks. Optional Online sales register that support this parameter: Orange Data.

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

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

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

Example of a payment form with parameters for the receipt

HTML
<form action="https://yoomoney.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 Wu\\", kg","paymentMethodType": "full_prepayment ","paymentSubjectType": "commodity"},{"quantity": 2, "price": {"amount": 200.00},  "tax": 3,"text": "Teacup, unit, 10% discount","paymentMethodType": "full_prepayment ","paymentSubjectType": "commodity"}]}'
        type="hidden"/>
        <input type="submit" value="Pay"/>
</form>