Чеки при платежах — Прием платежей по API ЮKassa

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

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

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

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

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

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

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

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

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.merchant-website.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

. Если что-то пойдет не так, сформируйте чек вручную в своей онлайн-кассе.

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

JSON
{
  "id": "227cf565-000f-5000-8000-1c9d1c6000fb",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "600.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000"
  },
  "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": "100001",
    "gateway_id": "1000001"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "600.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

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

Чтобы сформировать чек прихода, отправьте Ю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_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"
            }
          }
        ]
      }'

В ответ Ю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_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

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

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"
      }
    },
  ]
}

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

Основы проведения платежей Неуспешные платежи Чеки при возвратах Справочник значений параметров для чеков

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

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

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

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