YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Receipts for payments
This article describes the procedure of making payments with automatic registration of receipts in the Moi nalog service.
 
How it works
To register a receipt, you need to prepare data about products or services as well as the user's contact information: email address or a phone number where YooMoney could send the link to the registered receipt. This data must be specified in the receipt object in the same request as the payment data. The procedure depends on how you make the payment: in one or two stages.
One-stage payment
The receipt data must be sent during payment creation.
Payment in two stages
The receipt data must be sent during payment creation.
During payment capture:
  • If you capture the full amount, receipt details are not required. With full capture, your recorded income does not change, so a new receipt is not needed.
  • If you capture only part of the amount, then you must additionally specify the data for the receipt in the payment confirmation request. YooMoney will cancel the old receipt and register a new one with the data that you provide in the request.
  • If you cancel a payment, receipt details are not required. YooMoney cancels the receipt, and a new receipt is not needed.
Receipts when creating a payment
To generate a receipt, create a payment  and specify the receipt object with the data for the receipt in the request: the customer object with the user's email or phone number and an items array with the data regarding products or services (maximum 6 positions).
The information that must be transferred for each product:
  • the description parameter with the name of the product or service;
  • the amount parameter with the amount per unit of product;
  • the quantity parameter specifying the quantity of goods (only integers, for example 1);
  • the vat_code parameter with the fixed value 1 (price without VAT).
No other data is needed.
Example of a payment request with receipt parameters
cURL
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "1000.00",
          "currency": "RUB"
        },
        "capture": true,
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "description": "Order No. 37",
        "metadata": {
            "order_id": "37"
        },
        "receipt": {
          "customer": {
            "email": "user@example.com"
          },
          "items": [
            {
              "description": "Spoon",
              "quantity": "10",
              "amount": {
                "value": "50.00",
                "currency": "RUB"
              },
              "vat_code": "1"
            },
            {
              "description": "Tea cup",
              "quantity": "2",
              "amount": {
                "value": "150.00",
                "currency": "RUB"
              },
              "vat_code": "1"
            },
            {
              "description": "Saucer",
              "quantity": "2",
              "amount": {
                "value": "100.00",
                "currency": "RUB"
              },
              "vat_code": "1"
            }
          ]
        }
      }'
The created payment object  will be returned in response.
You can find out if a receipt has been generated by the value of the receipt_registration parameter in the payment object . The receipt registration status is also displayed in the payment history of your YooMoney Merchant Profile. If something goes wrong, create a receipt manually in the Moi nalog service and send the link to the receipt to the user independently.
Example of the response body
JSON
{
    "id": "28646d50-000f-5000-a000-1fe4f81e5e88",
    "status": "succeeded",
    "paid": true,
    "amount": {
        "value": "1000.00",
        "currency": "RUB"
    },
    "authorization_details": {
        "rrn": "10000000000",
        "auth_code": "000000",
        "three_d_secure": {
            "applied": true
        }
    },
    "captured_at": "2022-08-22T21:44:55.506Z",
    "created_at": "2022-08-22T21:43:44.794Z",
    "description": "Order No. 37",
    "income_amount": {
        "value": "964.00",
        "currency": "RUB"
    },
    "metadata": {
        "order_id": "37"
    },
    "payment_method": {
        "type": "bank_card",
        "id": "28646d50-000f-5000-a000-1fe4f81e5e88",
        "saved": false,
        "card": {
            "first6": "555555",
            "last4": "4477",
            "expiry_month": "01",
            "expiry_year": "2030",
            "card_type": "MasterCard",
            "card_type": "MIR",
            "card_product": {
                "code": "MCP",
                "name": "MIR Privilege"
            },
            "issuer_country": "RU"
        },
        "title": "Bank card *4477"
    },
    "receipt_registration": "succeeded",
    "recipient": {
        "account_id": "100500",
        "gateway_id": "100700"
    },
    "refundable": true,
    "refunded_amount": {
        "value": "0.00",
        "currency": "RUB"
    },
    "test": false
}
If the payment status changes to canceled after the payment by the user, YooMoney will automatically cancel the receipt in the Moi nalog service.
Receipts on capture and cancellation of a payment
Full payment capture
If you capture the payment in full, your recorded income does not change.
To debit the entire amount, send a standard request for payment capture . Do not specify the receipt object.
Example of a request for full payment capture
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json'
Partial payment capture
To debit only a part of the amount, specify the receipt object with data for generating a new receipt in the request for payment capture . The receipt must contain data on the products and services purchased by the user.
Example of a request for partial payment capture
cURL
curl https://api.yookassa.ru/v3/payments/:id/capture \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "250.00",
          "currency": "RUB"
        },
        "receipt": {
          "customer": {
            "email": "user@example.com"
          },
          "items": [
            {
              "description": "Tea cup",
              "quantity": "1",
              "amount": {
                "value": "150.00",
                "currency": "RUB"
              },
              "vat_code": "1"
            },
            {
              "description": "Saucer",
              "quantity": "1",
              "amount": {
                "value": "100.00",
                "currency": "RUB"
              },
              "vat_code": "1"
            }
          ]
        }
      }'
YooMoney will cancel the old receipt generated during payment creation and register a new receipt with the data that you specified in the payment capture request.
Payment cancellation
If you cancel a payment, you do not need to specify receipt data. Send a standard request for payment cancellation .
Payment cancellation request example
cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{

      }'
During the payment cancellation, YooMoney will automatically cancel the payment receipt.
Memo on preparing data for receipts
Make sure that you are specifying the correct data for receipts in the receipt object:
  • the receipt object is specified only in requests for payment creation and requests for partial payment capture;
  • user's e-mail or phone number are provided (data is specified in the customer object);
  • no more than 6 positions in items;
  • for each product, items contains only the description, amount, quantity, vat_code parameters; there are no other parameters;
  • quantity contains only integers (without dot and fractional part);
  • vat_code is 1 everywhere;
  • the payment amount in amount matches the total receipt amount in the receipt object (to determine the total receipt amount, multiply quantity by amount for each product and add the resulting values for all products);
  • all amounts in the receipt are positive.
If something goes wrong, YooMoney will return an error.
See also