YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Чеки при платежах
В этой статье описано, как сформировать чек прихода при проведении платежа и чек зачета предоплаты при выдаче товара (если в заказе были товары с предоплатой).
 
Как это работает
Для регистрации чека вам нужно подготовить данные о товарах или услугах и контактные данные пользователя — адрес электронной почты, куда ЮKassa отправит ссылку на зарегистрированный чек.
Проведение платежа
При проведении платежа вы передаете данные для чека в объекте receipt в том же запросе, что и данные для платежа. Это нужно делать при проведении каждого платежа.
Порядок действий зависит от того, как вы проводите платеж — в одну или в две стадии.
Платеж в одну стадию
Данные для чека необходимо передавать при создании платежа.
Проведение платежа в одну стадию
Платеж в две стадии
Данные для чека необходимо передавать при создании платежа.
Создание платежа в две стадии
При подтверждении платежа:
  • Если списываете полную сумму, данные для чека не нужны. При полном подтверждении состав заказа не меняется, поэтому новый чек не нужен.
  • Если списываете только часть суммы, то в запросе на подтверждение платежа необходимо дополнительно передать данные для чека. ЮKassa сформирует два чека: чек возврата предыдущего заказа и новый чек прихода. Для чека возврата ЮKassa использует те данные, которые вы передали в запросе на создание платежа, а для нового чека прихода — те данные, которые вы передадите в запросе на подтверждение платежа.
  • Если отменяете платеж, данные для чека не нужны. ЮKassa создаст чек возврата на основе тех данных, которые вы передали в запросе на создание платежа.
Full payment capture
Partial payment capture
Payment cancelation
Полное подтверждение платежа
Чек зачета предоплаты
Если в чеке прихода были товары с предоплатой, при их выдаче вы формируете чек зачета предоплаты. Данные для этого чека необходимо передать отдельным запросом на создание чека. Подробнее о чеке зачета предоплаты
Создание чека зачета предоплаты
Статус регистрации чека
При проведении платежа статус регистрации чека вернется в объекте платежа  в параметре receipt_registration, при создании чека зачета предоплаты — в объекте чека  в параметре status. Также статус отображается в личном кабинете ЮKassa в истории платежей.
Если чек зарегистрировать не удалось (статус чека canceled) или если в течение трех дней с момента создания платежа чек не сформируется (чек останется в статусе pending), обратитесь в техническую поддержку ЮKassa.
Чеки при создании платежа
Чтобы провести платеж вместе с отправкой чека, создайте платеж : отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности, с данными о платеже (сумма платежа, данные для выбранного сценария интеграции и другие параметры) и с данными для чека в объекте receipt:
  • объект customer с электронной почтой пользователя и при необходимости другими данными о пользователе;
  • массив items с данными о товарах или услугах;
  • при необходимости параметры receipt_industry_details с отраслевым реквизитом чека и receipt_operational_details с операционным реквизитом чека.
Пример запроса на оплату с параметрами для чека
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": "1250.00",
          "currency": "RUB"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.example.com/return_url"
        },
        "capture": true,
        "description": "Order No. 37",
        "metadata": {
            "order_id": "37"
        },
        "receipt": {
          "customer": {
            "email": "user@example.com"
          },
          "items": [
            {
              "description": "Tailoring service",
              "quantity": "1.00",
              "amount": {
                "value": "250.00",
                "currency": "RUB"
              },
              "vat_code": "1",
              "payment_mode": "full_prepayment",
              "payment_subject": "commodity"
            },
            {
              "description": "Knitted top",
              "quantity": "2.00",
              "amount": {
                "value": "500.00",
                "currency": "RUB"
              },
              "vat_code": "4",
              "payment_mode": "full_prepayment",
              "payment_subject": "marked",
              "mark_mode": 0,
              "mark_code_info":
              {
                "gs_1m": "DFGwNDY0MDE1Mzg2NDQ5MjIxNW9vY2tOelDFuUFwJh05MUVFMDYdOTJXK2ZaMy9uTjMvcVdHYzBjSVR3NFNOMWg1U2ZLV0dRMWhHL0UrZi8ydkDvPQ=="
              },
              "measure": "piece"
            }
          ]
        }
      }'
В ответ вернется созданный объект платежа . Актуальный статус регистрации чека прихода можно узнать по значению параметра receipt_registration.
Пример тела ответа
JSON
{
    "id": "28646d50-000f-5000-a000-1fe4f81e5e88",
    "status": "succeeded",
    "paid": true,
    "amount": {
        "value": "1250.00",
        "currency": "RUB"
    },
    "authorization_details": {
        "rrn": "10000000000",
        "auth_code": "000000",
        "three_d_secure": {
            "applied": true
        }
    },
    "captured_at": "2023-05-22T21:44:55.506Z",
    "created_at": "2022-05-22T21:43:44.794Z",
    "description": "Order No. 37",
    "income_amount": {
        "value": "1205.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",
            "issuer_country": "US"
        },
        "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
}
Если после оплаты пользователем платеж перейдет в статус canceled, ЮKassa автоматически создаст чек возврата прихода.
Чеки при подтверждении и отмене платежа
Полное подтверждение платежа
Если вы подтверждаете платеж полностью, состав чека не меняется.
Для списания всей суммы целиком отправьте стандартный запрос на подтверждение платежа . Объект receipt не передавайте.
Пример запроса для полного подтверждения платежа
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'
В ответ вернется объект платежа  в актуальном статусе.
Частичное подтверждение платежа
Чтобы списать только часть суммы, в запросе на подтверждение платежа  вам необходимо передать объект receipt с данными для формирования нового чека. В чеке необходимо указать данные о тех товарах и услугах, которые пользователь в итоге приобрел.
Пример запроса для частичного подтверждения платежа
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": {
            "email": "user@example.com"
          },
          "items": [
            {
              "description": "Knitted top",
              "quantity": "1.00",
              "amount": {
                "value": "500.00",
                "currency": "RUB"
              },
              "vat_code": "4",
              "payment_mode": "full_prepayment",
              "payment_subject": "marked",
              "mark_mode": 0,
              "mark_code_info":
              {
                "gs_1m": "DFGwNDY0MDE1Mzg2NDQ5MjIxNW9vY2tOelDFuUFwJh05MUVFMDYdOTJXK2ZaMy9uTjMvcVdHYzBjSVR3NFNOMWg1U2ZLV0dRMWhHL0UrZi8ydkDvPQ=="
              },
              "measure": "piece"
            }
          ]
        }
      }'
ЮKassa создаст чек возврата на основе тех данных, которые вы передали при создании платежа, и зарегистрирует новый чек прихода с теми данными, которые вы указали в запросе на подтверждение платежа.
В ответ вернется объект платежа  в актуальном статусе. Актуальный статус регистрации чека прихода можно узнать по значению параметра receipt_registration.
Отмена платежа
Если вы отменяете платеж, данные для чека передавать не нужно. Отправьте стандартный запрос на отмену платежа .
Пример запроса на отмену платежа
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 '{

      }'
При отмене платежа ЮKassa автоматически сформирует чек возврата на основе тех данных, которые вы передали в запросе на создание платежа.
В ответ вернется объект платежа  в актуальном статусе. Актуальный статус регистрации чека возврата прихода можно узнать по значению параметра receipt_registration.
Чек зачета предоплаты
Чек зачета предоплаты нужен только в случае, если вы принимали предоплату или аванс за товары.
Чтобы сформировать чек зачета предоплаты, создайте чек : отправьте ЮKassa запрос с данными для аутентификации, ключом идемпотентности и данными для чека:
  • параметр type со значением payment (чек прихода);
  • параметр payment_id с идентификатором платежа, для которого создаете чек зачета предоплаты;
  • объект customer с электронной почтой пользователя и при необходимости другими данными о пользователе;
  • массив items с данными о товарах или услугах; все товары должны содержать содержать признак способа расчета «Полный расчет»;
  • параметр send со значением true;
  • массив settlements с суммой всех совершенных расчетов; например, если было несколько частичных предоплат, нужно передать общую сумму с типом расчета «Предоплата (аванс)»;
  • при необходимости параметры receipt_industry_details с отраслевым реквизитом чека и receipt_operational_details с операционным реквизитом чека.
Пример запроса на создание чека
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": {
          "email": "user@example.com"
        },
        "payment_id": "28646d50-000f-5000-a000-1fe4f81e5e88",
        "type": "payment",
        "send": "true",
        "items": [
          {
            "description": "Tailoring service",
            "quantity": "1.00",
            "amount": {
              "value": "250.00",
              "currency": "RUB"
            },
            "vat_code": "1",
            "payment_mode": "full_payment",
            "payment_subject": "commodity"
          },
          {
            "description": "Knitted top",
            "quantity": "2.00",
            "amount": {
              "value": "500.00",
              "currency": "RUB"
            },
            "vat_code": "4",
            "payment_mode": "full_payment",
            "payment_subject": "marked",
            "mark_mode": 0,
            "mark_code_info":
            {
              "gs_1m": "DFGwNDY0MDE1Mzg2NDQ5MjIxNW9vY2tOelDFuUFwJh05MUVFMDYdOTJXK2ZaMy9uTjMvcVdHYzBjSVR3NFNOMWg1U2ZLV0dRMWhHL0UrZi8ydkDvPQ=="
            },
            "measure": "piece"
          }
        ],
        "settlements": [
          {
            "type": "prepayment",
            "amount": {
              "value": "1250.00",
              "currency": "RUB"
            }
          }
        ]
      }'
В ответ на запрос придет объект чека .
JSON
{
    "id": "rt-2bf4503f-0001-0050-0e94-761f7451b8a6",
    "type": "payment",
    "payment_id": "28646d50-000f-5000-a000-1fe4f81e5e88",
    "status": "pending",
    "items": [
        {
            "description": "Tailoring service",
            "quantity": 1.000,
            "amount": {
                "value": "250.00",
                "currency": "RUB"
            },
            "vat_code": 1,
            "payment_subject": "service",
            "payment_mode": "full_payment",
            "payment_subject_industry_details": []
        },
        {
            "description": "Топ из вязаного трикотажа (Молочный) (S)",
            "quantity": 2.000,
            "amount": {
                "value": "500.00",
                "currency": "RUB"
            },
            "vat_code": 4,
            "payment_subject": "marked",
            "payment_mode": "full_payment",
            "mark_code_info": {
                "gs_1m": "DFGwNDY0MDE1Mzg2NDQ5MjIxNW9vY2tOelDFuUFwJh05MUVFMDYdOTJXK2ZaMy9uTjMvcVdHYzBjSVR3NFNOMWg1U2ZLV0dRMWhHL0UrZi8ydkDvPQ=="
            },
            "measure": "piece",
            "payment_subject_industry_details": [],
            "mark_mode": "0"
        }
    ],
    "settlements": [
        {
            "type": "cashless",
            "amount": {
                "value": "1250.00",
                "currency": "RUB"
            }
        }
    ],
    "receipt_industry_details": []
}
Памятка по подготовке данных для чеков
Проверьте, что вы корректно передаете данные для чеков в объекте receipt:
  • переданы все обязательные параметры;
  • во всех параметрах непустые значения;
  • значения параметров переданы в нужном формате;
  • в чеке не более 100 товаров;
  • сумма платежа в amount совпадает с общей суммой чека в receipt (чтобы определить сумму чека, для каждого товара умножьте quantity на amount и просуммируйте получившиеся значения по всем товарам);
  • все суммы в чеке положительные;
  • в данных для чека нет подакцизных товаров;
  • в данных для чека нет товаров с частичной предоплатой, авансом или кредитом.
Если что-то будет не так, ЮKassa вернет ошибку.
See also