YooMoney API
Old versions of the API
Help
Sign up for YooMoney
Parameters for creating a receipt
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
ParameterTypeDescription
customer
Object
User information.
Required if customerContact is not specified.
customerContact
string,
64 characters
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
Required
Parameters of nested objects
ParameterTypeDescription
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.
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>
See also
Payments by 54-FZ Sending details for the receipt