Auto-sending of receipts for the self-employed: receipts for payments

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.

If you created the payment before enabling auto-sending of receipts while capturing or canceling it after you've activated the option, you will need to correct or cancel the receipt independently. It will not be possible to manage these receipts via the API.

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
PHP
Python
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

Only for payments processed in two stages.

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