Receipts for payments — Payment acceptance via the YooMoney API

Receipts for payments

Receipts reflect the status of mutual settlements between you and the user, confirming that the user has made the payment, and you in turn have provided them with the payment subject, for example, goods. If payment and delivery of the goods are separated in time, for example, when the goods are delivered by courier, you will need to generate an additional receipt when dispatching the goods.

General scenario

Select the scenario for sending the receipt.
Create a payment receipt in the request for creating a payment or as a separate request (depending on the selected scenario for sending the receipt).
If the payment receipt contains goods with prepayment, create a transaction completion receipt when dispatching the goods.

Payment receipt in the request for creating a payment

If you send receipts using one of the following scenarios: Payment and receipt at the same time or Payment after receipt, data for creating the receipt must be sent during payment creation and partial capture (if you use two-stage payments).

Payment creation

To generate a receipt for a processed payment, create a payment and specify the receipt object in the request along with the data for online sales register.

If you’re going to accept a payment from a legal entity via SberBank Business Online, you don’t need to send the receipt object with the data for the receipt.

Example of a request for payment 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": "600.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "receipt": {
          "customer": {
            "full_name": "Ivanov Ivan Ivanovich",
            "phone": "79000000000"
          },
          "items": [
            {
              "description": "Product name 1",
              "quantity": 2.000,
              "amount": {
                "value": "250.00",
                "currency": "RUB"
              },
              "vat_code": 2,
              "payment_mode": "full_prepayment",
              "payment_subject": "commodity"
            },
            {
              "description": "Product name 2",
              "quantity": 1.000,
              "amount": {
                "value": "100.00",
                "currency": "RUB"
              },
              "vat_code": 2,
              "payment_mode": "full_prepayment",
              "payment_subject": "commodity"
            }
          ]
        }
      }'

The created payment object will be returned in response.

If you use the Payment and receipt at the same time scenario, you can tell if the receipt has been generated or not by the value of the receipt_registration parameter. If something goes wrong, generate a receipt manually in your online sales register.

If you use the Payment after receipt scenario, the payment could return with the pending status and it'll have this status until the online sales register reports that a receipt has been generated successfully. If there's no response within five minutes, YooMoney will cancel the payment (the status will change to canceled) and return the money to the user.

Example of the response body

JSON
{
  "id": "227cf565-000f-5000-8000-1c9d1c6000fb",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "600.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "captured_at": "2018-05-03T10:17:31.487Z",
  "created_at": "2018-05-03T10:17:09.337Z",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "227cf565-000f-5000-8000-1c9d1c6000fb",
    "saved": false,
    "card": {
      "first6": "411111",
      "last4": "1111",
      "expiry_month": "01",
      "expiry_year": "2020",
      "card_type": "Mir",
      "card_product": {
        "code": "MCP",
        "name": "MIR Privilege"
      },
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *1111"
  },
  "receipt_registration": "pending",
  "recipient": {
    "account_id": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  }
}

If after the user’s payment the status changes to canceled, YooMoney will automatically send the data for generating a refund receipt to the online sales register.

Partial capture

If you process payments in two stages, partial capture will result in two new receipts: one for the refund of the previous payment, the other for the payment with corrected details. So if you want to partially capture a payment, send the receipt object with the data for generating a new receipt in the request for capture .

Example of request with a partial 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": "500.00",
          "currency": "RUB"
        },
        "receipt": {
          "customer": {
            "full_name": "Ivanov Ivan Ivanovich",
            "phone": "79000000000"
          },
          "items": [
            {
              "description": "Product name 1",
              "quantity": 2.000,
              "amount": {
                "value": "250.00",
                "currency": "RUB"
              },
              "vat_code": 2,
              "payment_mode": "full_prepayment",
              "payment_subject": "commodity"
            }
          ]
        }
      }'

If you capture the total amount, don’t send the data for the receipt.

Payment receipt in a separate request

If you send receipts by the Receipt after payment scenario, data for generating the receipt must be sent in a separate request.

In this case, request for creating the payment must not include the receipt object. In response to the request containing the receipt object YooMoney will return an error.

Payment receipts must be created for payments waiting for your capture (payment object with waiting_for_capture status) or successful payments (payment object with succeeded status). You can create up to 30 receipts for one payment.

Receipt creation

To create a payment receipt, send a request for creating a receipt to YooMoney. In this request, specify payment ID (payment_id) that you’re generating the receipt for, the type parameter with the payment value, and other necessary parameters.

Example of request for creating a receipt separately from payment

cURL
PHP
Python
curl https://api.yookassa.ru/v3/receipts \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "customer": {
          "full_name": "Ivanov Ivan Ivanovich",
          "email": "email@email.ru",
          "phone": "7100000000",
          "inn": "6321000014"
        },
        "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f",
        "type": "payment",
        "send": "true",
        "items": [
          {
            "description": "Product name 1",
            "quantity": 2.000,
            "amount": {
              "value": "250.00",
              "currency": "RUB"
            },
            "vat_code": 2,
            "payment_mode": "full_prepayment",
            "payment_subject": "commodity",
            "country_of_origin_code": "CN"
          },
          {
            "description": "Product name 2",
            "quantity": 1.000,
            "amount": {
              "value": "100.00",
              "currency": "RUB"
            },
            "vat_code": 2,
            "payment_mode": "full_prepayment",
            "payment_subject": "commodity",
            "country_of_origin_code": "CN"
          }
        ],
        "settlements": [
          {
            "type": "cashless",
            "amount": {
              "value": "600.00",
              "currency": "RUB"
            }
          }
        ]
      }'

YooMoney will send you the receipt object in response.

Example of the response body

JSON
{
  "id": "rt_1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "payment",
  "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f",
  "status": "pending",
  "items": [
    {
      "description": "Product name 1",
      "quantity": 2.000,
      "amount": {
        "value": "250.00",
        "currency": "RUB"
      },
      "vat_code": 2,
      "payment_mode": "full_prepayment",
      "payment_subject": "commodity",
      "country_of_origin_code": "CN"
    },
    {
      "description": "Product name 2",
      "quantity": 1.000,
      "amount": {
        "value": "100.00",
        "currency": "RUB"
      },
      "vat_code": 2,
      "payment_mode": "full_prepayment",
      "payment_subject": "commodity",
      "country_of_origin_code": "CN"
    }
  ],
  "settlements": [
    {
      "type": "cashless",
      "amount": {
        "value": "600.00",
        "currency": "RUB"
      }
    }
  ]
}

Partial capture

If you process payments in two stages, then after the partial capture you must generate two new receipts: refund receipt for the initial payment (full amount) and payment receipt with amended data.

In this case, request for capture should be sent without the receipt object.

If you capture the entire amount, you need to create one payment receipt after the payment status changes to waiting_for_capture.

Transaction completion receipt

Transaction completion is only required if you have accepted a prepayment or advance payment for products. Method and procedure for generating the transaction completion receipt are not dependent on the selected scenario for sending the receipts.

To generate a transaction completion receipt, send a request for creating a payment receipt (type with the payment value). All products in this receipt must include the “Full Payment” payment method attribute. Specify the amount of all completed settlements in the settlements object. For example, if there was a number of partial prepayments, specify the overall amount with the “Prepayment (advance payment)” settlement type.

Example of request for creating a receipt

cURL
PHP
Python
curl https://api.yookassa.ru/v3/receipts \
  -X POST \
  -u <Shop ID>:<Secret Key> \
  -H 'Idempotence-Key: <Idempotence Key>' \
  -H 'Content-Type: application/json' \
  -d '{
        "customer": {
          "full_name": "Ivanov Ivan Ivanovich",
          "email": "email@email.ru",
          "phone": "79211234567",
          "inn": "6321341814"
        },
        "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f",
        "type": "payment",
        "send": "true",
        "items": [
          {
            "description": "Product name 1",
            "quantity": 2.000,
            "amount": {
              "value": "250.00",
              "currency": "RUB"
            },
            "vat_code": 2,
            "payment_mode": "full_payment",
            "payment_subject": "commodity",
            "country_of_origin_code": "CN"
          },
          {
            "description": "Product name 2",
            "quantity": 1.000,
            "amount": {
              "value": "100.00",
              "currency": "RUB"
            },
            "vat_code": 2,
            "payment_mode": "full_payment",
            "payment_subject": "commodity",
            "country_of_origin_code": "CN"
          }
        ],
        "settlements": [
          {
            "type": "prepayment",
            "amount": {
              "value": "600.00",
              "currency": "RUB"
            }
          }
        ]
      }'

The receipt object will be sent in response.

JSON
{
  "id": "rt_1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "payment",
  "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f",
  "status": "pending",
  "items": [
    {
      "description": "Product name 1",
      "quantity": 2.000,
      "amount": {
        "value": "250.00",
        "currency": "RUB"
      },
      "vat_code": 2,
      "payment_mode": "full_payment",
      "payment_subject": "commodity",
      "country_of_origin_code": "CN"
    },
    {
      "description": "Product name 2",
      "quantity": 1.000,
      "amount": {
        "value": "100.00",
        "currency": "RUB"
      },
      "vat_code": 2,
      "payment_mode": "full_payment",
      "payment_subject": "commodity",
      "country_of_origin_code": "CN"
    }
  ],
  "settlements": [
    {
      "type": "prepayment",
      "amount": {
        "value": "600.00",
        "currency": "RUB"
      }
    }
  ]
}

Checklist for preparing the data for receipts

Correctness of requests

Make sure that you’re correctly sending the data for receipts in the receipt object:

data is sent in the corresponding request (depends on the scenario for sending the receipts);
all required parameters are included;
parameters values are sent in the required formats;
receipt contains no more than 100 items;
payment amount corresponds to the total receipt amount (to determine the receipt amount, multiply quantity by amount for each item, then add them up);
all amounts in the receipt are positive.

If something goes wrong, YooMoney will return an error.

Correctness of data

Make sure that the data you’re sending meets the requirements of 54-FZ and the restrictions of online sales registers:

the excise parameter is only specified for the products with the “Excisable goods” payment subject attribute;
a separate receipt is created for products sold on credit: it’s forbidden to have products with the “Loan” payment method attribute in the same receipt as the products with other payment method attributes;
the product_code, country_of_origin_code, customs_declaration_number parameters are only specified for products with the “Product”, “Excisable goods”, “Several subjects”, “Other” payment subject attributes.

If something goes wrong, the online sales register won’t generate a receipt: the error information will be shown in the payment history. The payment status will depend on the scenario for sending the receipts: for Payment after receipt, YooMoney will cancel the payment and automatically generate the Refund receipt; for other scenarios, the payment will be processed.