Отправка чеков сторонней онлайн-кассе: чеки при платежах

Чеки при платежах

Чеки отражают статус взаиморасчетов между вами и пользователем и подтверждают, что пользователь внес оплату, а вы предоставили ему предмет расчета, например товар. Если оплата и выдача товара разнесены по времени, например при доставке товара курьером, вам нужно будет сформировать дополнительный чек при выдаче товара.

Общий сценарий

Выберите сценарий отправки чека.
Сформируйте чек прихода в запросе на создание платежа или отдельным запросом (зависит от выбранного сценария отправки чека).
Если в чеке прихода были товары с предоплатой, при их выдаче сформируйте чек зачета предоплаты.

Чек прихода в запросе на создание платежа

Если вы отправляете чеки по одному из сценариев: Платеж и чек одновременно или Сначала чек, потом платеж, данные для формирования чека необходимо передавать при создании платежа и при частичном подтверждении (в случае двухстадийной оплаты).

Создание платежа

Чтобы сформировать чек, создайте платеж и передайте в запросе объект receipt с данными для онлайн-кассы.

Если вы собираетесь принять платеж от юридического лица через СберБанк Бизнес Онлайн, вам не нужно передавать объект receipt с данными для чека.

Пример запроса на оплату с параметрами для чека

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H '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": "Иванов Иван Иванович",
            "phone": "79000000000"
          },
          "items": [
            {
              "description": "Наименование товара 1",
              "quantity": "2.00",
              "amount": {
                "value": "250.00",
                "currency": "RUB"
              },
              "vat_code": "2",
              "payment_mode": "full_prepayment",
              "payment_subject": "commodity"
            },
            {
              "description": "Наименование товара 2",
              "quantity": "1.00",
              "amount": {
                "value": "100.00",
                "currency": "RUB"
              },
              "vat_code": "2",
              "payment_mode": "full_prepayment",
              "payment_subject": "commodity"
            }
          ]
        }
      }'

В ответ вернется созданный объект платежа .

Если вы используете сценарий Платеж и чек одновременно, то вы можете узнать, сформировался ли чек, по значению параметра receipt_registration. Если что-то пойдет не так, сформируйте чек вручную в своей онлайн-кассе.

Если вы используете сценарий Сначала чек, потом платеж, то платеж может вернуться в статусе pending и будет находиться в нём до тех пор, пока онлайн-касса не сообщит об успешной регистрации чека. Если за пять минут ответ не придет, ЮKassa отменит платеж (он перейдет в статус canceled) и вернет деньги пользователю.

Пример тела ответа

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": "Visa",
      "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"
  }
}

Если после оплаты пользователем платеж перейдет в статус canceled, ЮKassa автоматически передаст онлайн-кассе данные для формирования чека возврата.

Частичное подтверждение платежа

Если вы проводите платежи в две стадии, то при частичном подтверждении платежа будет формироваться два новых чека: один — для возврата предыдущего платежа, второй — для платежа с учетом скорректированных данных. Поэтому если вы хотите подтвердить платеж частично, в запросе на подтверждение вам необходимо передать объект receipt с данными для формирования нового чека.

Пример запроса с частичным подтверждением

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/:id/capture \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "500.00",
          "currency": "RUB"
        },
        "receipt": {
          "customer": {
            "full_name": "Иванов Иван Иванович",
            "phone": "79000000000"
          },
          "items": [
            {
              "description": "Наименование товара 1",
              "quantity": "2.00",
              "amount": {
                "value": "250.00",
                "currency": "RUB"
              },
              "vat_code": "2",
              "payment_mode": "full_prepayment",
              "payment_subject": "commodity"
            }
          ]
        }
      }'

Если вы подтверждаете всю сумму целиком, данные для чека передавать не нужно.

Чек прихода отдельным запросом

Если вы отправляете чеки по сценарию Сначала платеж, потом чек, данные для формирования чека прихода нужно передавать отдельным запросом.

В этом случае запрос на создание платежа нужно передавать без объекта receipt. В ответ на запрос с объектом receipt ЮKassa вернет ошибку.

Чек прихода необходимо формировать для платежа, который ожидает вашего подтверждения (объект платежа в статусе waiting_for_capture) или уже успешно завершен (объект платежа в статусе succeeded). Для одного платежа можно создать не более 15 чеков.

Создание чека

Чтобы сформировать чек прихода, отправьте ЮKassa запрос на создание чека . В запросе передайте идентификатор платежа (payment_id), для которого формируете чек, параметр type со значением payment и другие необходимые параметры.

Пример запроса на создание чека отдельно от платежа

cURL
PHP
Python
curl https://api.yookassa.ru/v3/receipts \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "customer": {
          "full_name": "Иванов Иван Иванович",
          "email": "email@email.ru",
          "phone": "7100000000",
          "inn": "6321000014"
        },
        "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f",
        "type": "payment",
        "send": "true",
        "items": [
          {
            "description": "Наименование товара 1",
            "quantity": "2.00",
            "amount": {
              "value": "250.00",
              "currency": "RUB"
            },
            "vat_code": "2",
            "payment_mode": "full_prepayment",
            "payment_subject": "commodity",
            "country_of_origin_code": "CN"
          },
          {
            "description": "Наименование товара 2",
            "quantity": "1.00",
            "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"
            }
          }
        ]
      }'

В ответ ЮKassa отправит объект чека .

Пример тела ответа

JSON
{
  "id": "rt_1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "payment",
  "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f",
  "status": "pending",
  "items": [
    {
      "description": "Наименование товара 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": "Наименование товара 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"
      }
    }
  ]
}

Частичное подтверждение платежа

Если вы принимаете оплату в две стадии, то после частичного подтверждения платежа нужно сформировать два новых чека: чек возврата прихода первоначального платежа (на полную сумму) и чек прихода с учетом скорректированных данных.

В этом случае запрос на подтверждение необходимо отправлять без объекта receipt.

Если вы подтверждаете всю сумму целиком, нужно сформировать только один чек прихода, когда платеж перейдет в статус waiting_for_capture.

Чек зачета предоплаты

Чек зачета предоплаты нужен только в случае, если вы принимали предоплату или аванс за товары. Способ и порядок формирования чека зачета предоплаты не зависит от выбранного сценария отправки чеков.

Чтобы сформировать чек зачета предоплаты, отправьте запрос на создание чека прихода (type со значением payment). Все товары в этом чеке должны содержать признак способа расчета «Полный расчет». Укажите в объекте settlements сумму всех совершенных расчетов. Например, если было несколько частичных предоплат, нужно передать общую сумму с типом расчета «Предоплата (аванс)».

Пример запроса на создание чека

cURL
PHP
Python
curl https://api.yookassa.ru/v3/receipts \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "customer": {
          "full_name": "Иванов Иван Иванович",
          "email": "email@email.ru",
          "phone": "79211234567",
          "inn": "6321341814"
        },
        "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f",
        "type": "payment",
        "send": "true",
        "items": [
          {
            "description": "Наименование товара 1",
            "quantity": "2.00",
            "amount": {
              "value": "250.00",
              "currency": "RUB"
            },
            "vat_code": "2",
            "payment_mode": "full_payment",
            "payment_subject": "commodity",
            "country_of_origin_code": "CN"
          },
          {
            "description": "Наименование товара 2",
            "quantity": "1.00",
            "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"
            }
          }
        ]
      }'

В ответ на запрос придет объект чека .

JSON
{
  "id": "rt_1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "payment",
  "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f",
  "status": "pending",
  "items": [
    {
      "description": "Наименование товара 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": "Наименование товара 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"
      }
    }
  ]
}

Памятка по подготовке данных для чеков

Корректность запросов

Проверьте, что вы корректно передаете данные для чеков в объекте receipt:

данные переданы в соответствующем запросе (зависит от сценария отправки чеков);
переданы все обязательные параметры;
значения параметров переданы в нужном формате;
в чеке не более 100 товаров;
сумма платежа в amount совпадает с общей суммой чека в receipt (чтобы определить сумму чека, для каждого товара умножьте quantity на amount и просуммируйте получившиеся значения по всем товарам);
все суммы в чеке положительные.

Если что-то будет не так, ЮKassa вернет ошибку.

Корректность данных

Проверьте, что передаваемые данные соответствуют требованиям 54-ФЗ и ограничениям онлайн-касс:

параметр excise только у товаров с признаком предмета расчета «Подакцизный товар»;
для товаров, продаваемых в кредит, создан отдельный чек: нельзя, чтобы в одном чеке были товары с признаком способа расчета «Кредит» и товары с другими признаками способа расчета;
параметры product_code, country_of_origin_code, customs_declaration_number только у товаров с признаками предмета расчета «Товар», «Подакцизный товар», «Несколько вариантов», «Другое».

Если что-то будет не так, онлайн-касса не сформирует чек — информация об ошибке отобразится в истории платежей. Статус платежа будет зависеть от сценария отправки чеков: в сценарии Сначала чек, потом платеж ЮKassa отменит платеж и автоматически сформирует чек возврата прихода; в других сценариях платеж пройдет.

Что почитать еще

Основы проведения платежей Получение информации о платеже Коды ответа (состояния) HTTP Выгрузка данных по чекам