Справочник API ЮKassa

В справочнике API вы найдете описание всех методов API ЮKassa. С помощью этого API вы можете работать с онлайн-платежами: отправлять запросы на оплату, сохранять платежную информацию для повторных списаний, совершать возвраты и многое другое.

Подробнее об интеграции по API ЮKassa

cURL

PHP

Python

Платежи

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

cURL

PHP

Python

Объект платежа

Объект платежа (

Payment

) содержит всю информацию о платеже, актуальную на текущий момент времени. Он формируется при создании платежа и приходит в ответ на любой запрос, связанный с платежами.

Описание параметров

Параметры

Описание

id

string, required

Идентификатор платежа в ЮKassa.

status

string, required

Статус платежа. Возможные значения:

pending

,

waiting_for_capture

,

succeeded

и

canceled

. Подробнее про жизненный цикл платежа

amount

object, required

Сумма платежа. Иногда партнеры ЮKassa берут с пользователя дополнительную комиссию, которая не входит в эту сумму.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

income_amount

object, optional

Сумма платежа, которую получит магазин, — значение

amount

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

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

description

string, optional

Описание транзакции (не более 128 символов), которое вы увидите в личном кабинете ЮKassa, а пользователь — при оплате. Например: «Оплата заказа № 72 для user@yoomoney.ru».

recipient

object, required

Получатель платежа.

Вложенные параметры

account_id

string, required

Идентификатор магазина в ЮKassa.

gateway_id

string, required

Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта.

payment_method

object, optional

Способ оплаты

, который был использован для этого платежа.

Вложенные параметры

Способы оплаты

Альфа-Клик

type

string, required

Значение —

alfabank

.

Код способа оплаты.

id

string, required

Идентификатор способа оплаты.

saved

boolean, required

С помощью сохраненного способа оплаты можно проводить безакцептные списания .

title

string, optional

Название способа оплаты.

login

string, optional

Логин пользователя в Альфа-Клике (привязанный телефон или дополнительный логин).

captured_at

string, optional

Время подтверждения платежа. Указывается по UTC и передается в формате ISO 8601.

created_at

string, required

Время создания заказа. Указывается по UTC и передается в формате ISO 8601. Пример:

2017-11-03T11:52:31.827Z

expires_at

string, optional

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

waiting_for_capture

будет автоматически отменен. Указывается по UTC и передается в формате ISO 8601. Пример:

2017-11-03T11:52:31.827Z

confirmation

object, optional

Выбранный способ подтверждения платежа. Присутствует, когда платеж ожидает подтверждения от пользователя. Подробнее о сценариях подтверждения

Вложенные параметры

Сценарии подтверждения

Embedded

type

string, required

Значение —

embedded

.

Код сценария подтверждения.

confirmation_token

string, required

Токен для инициализации платежного виджета ЮKassa .

test

boolean, required

Признак тестовой операции.

refunded_amount

object, optional

Сумма, которая вернулась пользователю. Присутствует, если у этого платежа есть успешные возвраты.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

paid

boolean, required

Признак оплаты заказа.

refundable

boolean, required

Возможность провести возврат по API.

receipt_registration

string, optional

Статус доставки данных для чека в онлайн-кассу (

pending

,

succeeded

или

canceled

). Присутствует, если вы используете решение ЮKassa для работы по 54-ФЗ .

metadata

object, optional

Любые дополнительные данные, которые нужны вам для работы с платежами (например, номер заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от ЮKassa. Ограничения: максимум 16 ключей, имя ключа не больше 32 символов, значение ключа не больше 512 символов, тип данных — строка в формате UTF-8.

cancellation_details

object, optional

Комментарий к статусу

canceled

: кто отменил платеж и по какой причине. Подробнее про неуспешные платежи

Вложенные параметры

party

string, required

Участник процесса платежа, который принял решение об отмене транзакции. Может принимать значения

yoo_money

,

payment_network

и

merchant

. Подробнее про инициаторов отмены платежа

reason

string, required

Причина отмены платежа. Перечень и описание возможных значений

authorization_details

object, optional

Данные об авторизации платежа.

Вложенные параметры

rrn

string, optional

Retrieval Reference Number — уникальный идентификатор транзакции в системе эмитента. Используется при оплате банковской картой.

auth_code

string, optional

Код авторизации банковской карты. Выдается эмитентом и подтверждает проведение авторизации.

transfers

array, optional

Данные о распределении денег — сколько и в какой магазин нужно перевести. Присутствует, если вы используете решение ЮKassa для платформ .

Вложенные параметры

account_id

string, required

Идентификатор магазина, в пользу которого вы принимаете оплату. Выдается ЮKassa, отображается в разделе Продавцы личного кабинета (столбец shopId).

amount

object, required

Сумма, которую необходимо перечислить магазину.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

status

string, required

Статус распределения денег между магазинами. Возможные значения:

pending

,

waiting_for_capture

,

succeeded

,

canceled

.

platform_fee_amount

object, optional

Комиссия за проданные товары и услуги, которая удерживается с магазина в вашу пользу.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

metadata

object, optional

Любые дополнительные данные, которые нужны вам для работы с платежами (например, номер заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от ЮKassa. Ограничения: максимум 16 ключей, имя ключа не больше 32 символов, значение ключа не больше 512 символов, тип данных — строка в формате UTF-8.

Пример объекта Payment

{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-07-18T10:51:18.139Z",
  "description": "Заказ №72",
  "expires_at": "2018-07-25T10:52:00.233Z",
  "metadata": {},
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
  "income_amount": {
    "value": "1.97",
    "currency": "RUB"
  }
}

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

Чтобы принять оплату, необходимо создать объект платежа —

Payment

. Он содержит всю необходимую информацию для проведения оплаты (сумму, валюту и статус). У платежа линейный жизненный цикл, он последовательно переходит из статуса в статус.

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

Описание параметров запроса

Параметры запроса

Описание

amount

object, required

Сумма платежа. Иногда партнеры ЮKassa берут с пользователя дополнительную комиссию, которая не входит в эту сумму.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

description

string, optional

Описание транзакции (не более 128 символов), которое вы увидите в личном кабинете ЮKassa, а пользователь — при оплате. Например: «Оплата заказа № 72 для user@yoomoney.ru».

receipt

object, optional

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

Вложенные параметры

customer

object, optional

Информация о пользователе. Необходимо указать как минимум контактные данные: электронную почту (

customer.email

) или номер телефона (

customer.phone

).

Вложенные параметры

full_name

string, optional

Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные. Не более 256 символов.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.

inn

string, optional

ИНН пользователя (10 или 12 цифр).

email

string, optional

Электронная почта пользователя.

phone

string, optional

Телефон пользователя. Указывается в формате ITU-T E.164, например

79000000000

.

items

array, required

Список товаров в заказе (не более 100 товаров).

Вложенные параметры

description

string, required

Название товара (не более 128 символов).

quantity

string, required

Количество товара. Максимально возможное значение зависит от модели вашей онлайн-кассы.

amount

object, required

Цена товара.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

vat_code

number, required

Ставка НДС. Возможные значения — числа от 1 до 6. Подробнее про коды ставок НДС

payment_subject

string, optional

Признак предмета расчета. Перечень возможных значений

payment_mode

string, optional

Признак способа расчета. Перечень возможных значений

product_code

string, optional

Код товара — уникальный номер, который присваивается экземпляру товара при маркировке.
Формат: число в шестнадцатеричном представлении с пробелами. Максимальная длина — 32 байта. Пример:

00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00

.
Обязательный параметр, если товар нужно маркировать.

country_of_origin_code

string, optional

Код страны происхождения товара по общероссийскому классификатору стран мира (OК (MК (ИСО 3166) 004-97) 025-2001). Пример:

RU

.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

customs_declaration_number

string, optional

Номер таможенной декларации (от 1 до 32 символов).
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

excise

string, optional

Сумма акциза товара с учетом копеек. Десятичное число с точностью до 2 символов после точки.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

tax_system_code

number, optional

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

phone

string, optional

Телефон пользователя. Указывается в формате ITU-T E.164, например

79000000000

.

email

string, optional

Электронная почта пользователя.

recipient

object, optional

Получатель платежа. Нужен, если вы разделяете потоки платежей в рамках одного аккаунта или создаете платеж в адрес другого аккаунта.

Вложенные параметры

gateway_id

string, required

Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта.

payment_token

string, optional

Одноразовый токен для проведения оплаты, сформированный с помощью веб или мобильного SDK .

payment_method_id

string, optional

Идентификатор сохраненного способа оплаты .

payment_method_data

object, optional

Данные для оплаты конкретным способом (

payment_method

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

Вложенные параметры

Способы оплаты

Альфа-Клик

type

string, required

Значение —

alfabank

.

Код способа оплаты.

login

string, optional

Логин пользователя в Альфа-Клике. Обязателен для сценария External .

confirmation

object, optional

Данные, необходимые для инициирования выбранного сценария подтверждения платежа пользователем. Подробнее о сценариях подтверждения

Вложенные параметры

Сценарии подтверждения

Embedded

type

string, required

Значение —

embedded

.

Код сценария подтверждения.

locale

string, optional

Язык интерфейса, писем и смс, которые будет видеть или получать пользователь. Формат соответствует ISO/IEC 15897. Возможные значения:

ru_RU

,

en_US

,

de_DE

. Регистр важен.

save_payment_method

boolean, optional

Сохранение платежных данных (с их помощью можно проводить повторные безакцептные списания ). Значение

true

инициирует создание многоразового

payment_method

.

capture

boolean, optional

Автоматический прием

поступившего платежа.

client_ip

string, optional

IPv4 или IPv6-адрес пользователя. Если не указан, используется IP-адрес TCP-подключения.

metadata

object, optional

Любые дополнительные данные, которые нужны вам для работы с платежами (например, номер заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от ЮKassa. Ограничения: максимум 16 ключей, имя ключа не больше 32 символов, значение ключа не больше 512 символов, тип данных — строка в формате UTF-8.

airline

object, optional

Объект с данными для продажи авиабилетов . Используется только для платежей банковской картой.

Вложенные параметры

ticket_number

string, optional

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

ticket_number

— обязательный параметр. Если не знаете, тогда вместо

ticket_number

необходимо передать

booking_reference

с номером бронирования.

booking_reference

string, optional

Номер бронирования. Обязателен, если не передан

ticket_number

.

passengers

array, optional

Список пассажиров.

Вложенные параметры

first_name

string, required

Имя пассажира.

last_name

string, required

Фамилия пассажира.

legs

array, optional

Список перелетов.

Вложенные параметры

departure_airport

string, required

Код аэропорта вылета по справочнику IATA, например LED.

destination_airport

string, required

Код аэропорта прилета по справочнику IATA, например AMS.

departure_date

string, required

Дата вылета в формате YYYY-MM-DD по стандарту ISO 8601:2004.

carrier_code

string, optional

Код авиакомпании по справочнику IATA.

transfers

array, optional

Данные о распределении денег — сколько и в какой магазин нужно перевести. Необходимо передавать, если вы используете решение ЮKassa для платформ .

Вложенные параметры

account_id

string, required

Идентификатор магазина, в пользу которого вы принимаете оплату. Выдается ЮKassa, отображается в разделе Продавцы личного кабинета (столбец shopId).

amount

object, required

Сумма, которую необходимо перевести магазину.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

platform_fee_amount

object, optional

Комиссия за проданные товары и услуги, которая удерживается с магазина в вашу пользу.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

metadata

object, optional

Любые дополнительные данные, которые нужны вам для работы с платежами (например, номер заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от ЮKassa. Ограничения: максимум 16 ключей, имя ключа не больше 32 символов, значение ключа не больше 512 символов, тип данных — строка в формате UTF-8.

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/payments \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_method_data": {
          "type": "bank_card"
        },
        "confirmation": {
          "type": "redirect",
          "return_url": "https://www.merchant-website.com/return_url"
        },
        "description": "Заказ №72"
      }'

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

{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "pending",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "confirmation": {
    "type": "redirect",
    "return_url": "https://www.merchant-website.com/return_url",
    "confirmation_url": "https://yoomoney.ru/payments/external/confirmation?orderId=22e12f66-000f-5000-8000-18db351245c7"
  },
  "created_at": "2018-07-18T10:51:18.139Z",
  "description": "Заказ №72",
  "metadata": {
    
  },
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}

Список платежей

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

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

Если результатов больше, чем задано в

limit

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

next_cursor

с указателем на следующий фрагмент.

Подробнее о работе со списками

Описание параметров запроса

Параметры запроса

Описание

created_at.gte

string, optional

Фильтр по времени создания: время должно быть больше указанного значения или равно ему («с такого-то момента включительно»). Указывается в формате ISO 8601. Пример:

created_at.gte=2018-07-18T10:51:18.139Z

created_at.gt

string, optional

Фильтр по времени создания: время должно быть больше указанного значения («с такого-то момента, не включая его»). Указывается в формате ISO 8601. Пример:

created_at.gt=2018-07-18T10:51:18.139Z

created_at.lte

string, optional

Фильтр по времени создания: время должно быть меньше указанного значения или равно ему («по такой-то момент включительно»). Указывается в формате ISO 8601. Пример:

created_at.lte=2018-07-18T10:51:18.139Z

created_at.lt

string, optional

Фильтр по времени создания: время должно быть меньше указанного значения («по такой-то момент, не включая его»). Указывается в формате ISO 8601. Пример:

created_at.lt=2018-07-18T10:51:18.139Z

captured_at.gte

string, optional

Фильтр по времени подтверждения платежей: время должно быть больше указанного значения или равно ему («с такого-то момента включительно»). Указывается в формате ISO 8601. Пример:

captured_at.gte=2018-07-18T10:51:18.139Z

captured_at.gt

string, optional

Фильтр по времени подтверждения платежей: время должно быть больше указанного значения («с такого-то момента, не включая его»). Указывается в формате ISO 8601. Пример:

captured_at.gt=2018-07-18T10:51:18.139Z

captured_at.lte

string, optional

Фильтр по времени подтверждения платежей: время должно быть меньше указанного значения или равно ему («по такой-то момент включительно»). Указывается в формате ISO 8601. Пример:

captured_at.lte=2018-07-18T10:51:18.139Z

captured_at.lt

string, optional

Фильтр по времени подтверждения платежей: время должно быть меньше указанного значения («по такой-то момент, не включая его») Указывается в формате ISO 8601. Пример:

captured_at.lt=2018-07-18T10:51:18.139Z

payment_method

string, optional

Фильтр по коду способа оплаты . Пример:

payment_method=bank_card

status

string, optional

Фильтр по статусу платежа . Пример:

status=succeeded

limit

number, optional

Размер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример:

limit=50

Значение по умолчанию:

10

cursor

string, optional

Указатель на следующий фрагмент списка. Пример:

cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15

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

next_cursor

, полученное в ответе на предыдущий запрос. Используется, если в списке больше объектов, чем может поместиться в выдаче (

limit

), и конец выдачи не достигнут. Пример использования

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/payments \
  -u <Идентификатор магазина>:<Секретный ключ>

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

{
  "type": "list",
  "items": [
    {
      "id": "22e12f66-000f-5000-8000-18db351245c7",
      "status": "waiting_for_capture",
      "paid": true,
      "amount": {
        "value": "2.00",
        "currency": "RUB"
      },
      "created_at": "2018-07-18T10:51:18.139Z",
      "description": "Заказ №72",
      "expires_at": "2018-07-25T10:52:00.233Z",
      "metadata": {
        
      },
      "payment_method": {
        "type": "bank_card",
        "id": "22e12f66-000f-5000-8000-18db351245c7",
        "saved": false,
        "card": {
          "first6": "555555",
          "last4": "4444",
          "expiry_month": "07",
          "expiry_year": "2022",
          "card_type": "MasterCard",
          "issuer_country": "RU",
          "issuer_name": "Sberbank"
        },
        "title": "Bank card *4444"
      },
      "recipient": {
        "account_id": "100001",
        "gateway_id": "1000001"
      },
      "refundable": false,
      "test": false
    }
  ],
  "next_cursor": "37a5c87d-3984-51e8-a7f3-8de646d39ec15"
}

Информация о платеже

Запрос позволяет получить информацию о текущем состоянии платежа по его уникальному идентификатору.

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

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -u <Идентификатор магазина>:<Секретный ключ>

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

{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-07-18T10:51:18.139Z",
  "description": "Заказ №72",
  "expires_at": "2018-07-25T10:52:00.233Z",
  "metadata": {
    
  },
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}

Подтверждение платежа

Подтверждает вашу готовность принять платеж. После подтверждения платеж перейдет в статус

succeeded

. Это значит, что вы можете выдать товар или оказать услугу пользователю.

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

waiting_for_capture

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

canceled

, и деньги вернутся пользователю.

Подробнее о подтверждении и отмене платежей

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

Описание параметров запроса

Параметры запроса

Описание

amount

object, optional

Итоговая сумма, которая спишется с пользователя. Для платежей банковской картой или из кошелька ЮMoney можно указать часть исходной суммы, в этом случае остаток вернется пользователю.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

receipt

object, optional

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

Вложенные параметры

customer

object, optional

Информация о пользователе. Необходимо указать как минимум контактные данные: электронную почту (

customer.email

) или номер телефона (

customer.phone

).

Вложенные параметры

full_name

string, optional

Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные. Не более 256 символов.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.

inn

string, optional

ИНН пользователя (10 или 12 цифр).

email

string, optional

Электронная почта пользователя.

phone

string, optional

Телефон пользователя. Указывается в формате ITU-T E.164, например

79000000000

.

items

array, required

Список товаров в заказе (не более 100 товаров).

Вложенные параметры

description

string, required

Название товара (не более 128 символов).

quantity

string, required

Количество товара. Максимально возможное значение зависит от модели вашей онлайн-кассы.

amount

object, required

Цена товара.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

vat_code

number, required

Ставка НДС. Возможные значения — числа от 1 до 6. Подробнее про коды ставок НДС

payment_subject

string, optional

Признак предмета расчета. Перечень возможных значений

payment_mode

string, optional

Признак способа расчета. Перечень возможных значений

product_code

string, optional

Код товара — уникальный номер, который присваивается экземпляру товара при маркировке.
Формат: число в шестнадцатеричном представлении с пробелами. Максимальная длина — 32 байта. Пример:

00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00

.
Обязательный параметр, если товар нужно маркировать.

country_of_origin_code

string, optional

Код страны происхождения товара по общероссийскому классификатору стран мира (OК (MК (ИСО 3166) 004-97) 025-2001). Пример:

RU

.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

customs_declaration_number

string, optional

Номер таможенной декларации (от 1 до 32 символов).
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

excise

string, optional

Сумма акциза товара с учетом копеек. Десятичное число с точностью до 2 символов после точки.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

tax_system_code

number, optional

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

phone

string, optional

Телефон пользователя. Указывается в формате ITU-T E.164, например

79000000000

.

email

string, optional

Электронная почта пользователя.

airline

object, optional

Объект с данными для продажи авиабилетов . Используется только для платежей банковской картой.

Вложенные параметры

ticket_number

string, optional

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

ticket_number

— обязательный параметр. Если не знаете, тогда вместо

ticket_number

необходимо передать

booking_reference

с номером бронирования.

booking_reference

string, optional

Номер бронирования. Обязателен, если не передан

ticket_number

.

passengers

array, optional

Список пассажиров.

Вложенные параметры

first_name

string, required

Имя пассажира.

last_name

string, required

Фамилия пассажира.

legs

array, optional

Список перелетов.

Вложенные параметры

departure_airport

string, required

Код аэропорта вылета по справочнику IATA, например LED.

destination_airport

string, required

Код аэропорта прилета по справочнику IATA, например AMS.

departure_date

string, required

Дата вылета в формате YYYY-MM-DD по стандарту ISO 8601:2004.

carrier_code

string, optional

Код авиакомпании по справочнику IATA.

transfers

array, optional

Данные об актуальном распределении денег — сколько и в какой магазин нужно перевести. Необходимо передавать, если вы используете решение ЮKassa для платформ и подтверждаете часть платежа.

Вложенные параметры

account_id

string, required

Идентификатор магазина, в пользу которого вы принимаете оплату. Выдается ЮKassa, отображается в разделе Продавцы личного кабинета (столбец shopId).

amount

object, required

Сумма, которую необходимо перевести магазину.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

platform_fee_amount

object, optional

Комиссия за проданные товары и услуги, которая удерживается с магазина в вашу пользу.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/payments/{payment_id}/capture \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        }
      }'

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

{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "succeeded",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "captured_at": "2018-07-18T11:17:33.483Z",
  "created_at": "2018-07-18T10:51:18.139Z",
  "description": "Заказ №72",
  "metadata": {
    
  },
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}

Отмена платежа

Отменяет платеж, находящийся в статусе

waiting_for_capture

. Отмена платежа значит, что вы не готовы выдать пользователю товар или оказать услугу. Как только вы отменяете платеж, мы начинаем возвращать деньги на счет плательщика. Для платежей банковскими картами или из кошелька ЮMoney отмена происходит мгновенно. Для остальных способов оплаты возврат может занимать до нескольких дней.

Подробнее о подтверждении и отмене платежей

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

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/payments/{payment_id}/cancel \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{ }'

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

{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "canceled",
  "paid": false,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "created_at": "2018-07-18T10:51:18.139Z",
  "description": "Заказ №72",
  "metadata": {
    
  },
  "payment_method": {
    "type": "bank_card",
    "id": "22e12f66-000f-5000-8000-18db351245c7",
    "saved": false,
    "card": {
      "first6": "555555",
      "last4": "4444",
      "expiry_month": "07",
      "expiry_year": "2022",
      "card_type": "MasterCard",
      "issuer_country": "RU",
      "issuer_name": "Sberbank"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "refundable": false,
  "test": false
}

Возвраты

С помощью API можно возвращать платежи — полностью или частично. Порядок возврата зависит от способа оплаты (

payment_method

) исходного платежа. При оплате банковской картой деньги возвращаются на карту, которая была использована для проведения платежа. Как проводить возвраты

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

cURL

PHP

Python

Объект возврата

Объект возврата (

Refund

) содержит актуальную информацию о возврате успешного платежа. Он приходит в ответ на любой запрос, связанный с возвратами.

Описание параметров

Параметры

Описание

id

string, required

Идентификатор возврата платежа в ЮKassa.

payment_id

string, required

Идентификатор платежа в ЮKassa.

status

string, required

Статус возврата платежа. Возможные значения:

canceled

,

succeeded

.

created_at

string, required

Время создания возврата. Указывается по UTC и передается в формате ISO 8601, например

2017-11-03T11:52:31.827Z

amount

object, required

Сумма, возвращенная пользователю.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

description

string, optional

Основание для возврата денег пользователю.

sources

array, optional

Данные о том, с какого магазин и какую сумму нужно удержать для проведения возврата. Присутствует, если вы используете решение ЮKassa для платформ .

Вложенные параметры

account_id

string, required

Идентификатор магазина, для которого вы хотите провести возврат. Выдается ЮKassa, отображается в разделе Продавцы личного кабинета (столбец shopId).

amount

object, required

Сумма возврата.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

platform_fee_amount

object, optional

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

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

Пример объекта Refund

{
  "id": "216749f7-0016-50be-b000-078d43a63ae4",
  "status": "succeeded",
  "amount": {
    "value": "1",
    "currency": "RUB"
  },
  "created_at": "2017-10-04T19:27:51.407Z",
  "payment_id": "216749da-000f-50be-b000-096747fad91e"
}

Создание возврата

Создает возврат успешного платежа на указанную сумму. Платеж можно вернуть только в течение трех лет с момента его создания. Комиссия ЮKassa за проведение платежа не возвращается.

В ответ на запрос придет объект возврата в актуальном статусе.

Описание параметров запроса

Параметры запроса

Описание

payment_id

string, required

Идентификатор платежа в ЮKassa.

amount

object, required

Сумма, которую нужно вернуть пользователю.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

description

string, optional

Комментарий к возврату, основание для возврата денег пользователю.

receipt

object, optional

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

Вложенные параметры

customer

object, optional

Информация о пользователе. Необходимо указать как минимум контактные данные: электронную почту (

customer.email

) или номер телефона (

customer.phone

).

Вложенные параметры

full_name

string, optional

Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные. Не более 256 символов.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.

inn

string, optional

ИНН пользователя (10 или 12 цифр).

email

string, optional

Электронная почта пользователя.

phone

string, optional

Телефон пользователя. Указывается в формате ITU-T E.164, например

79000000000

.

items

array, required

Список товаров в заказе (не более 100 товаров).

Вложенные параметры

description

string, required

Название товара (не более 128 символов).

quantity

string, required

Количество товара. Максимально возможное значение зависит от модели вашей онлайн-кассы.

amount

object, required

Цена товара.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

vat_code

number, required

Ставка НДС. Возможные значения — числа от 1 до 6. Подробнее про коды ставок НДС

payment_subject

string, optional

Признак предмета расчета. Перечень возможных значений

payment_mode

string, optional

Признак способа расчета. Перечень возможных значений

product_code

string, optional

Код товара — уникальный номер, который присваивается экземпляру товара при маркировке.
Формат: число в шестнадцатеричном представлении с пробелами. Максимальная длина — 32 байта. Пример:

00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00

.
Обязательный параметр, если товар нужно маркировать.

country_of_origin_code

string, optional

Код страны происхождения товара по общероссийскому классификатору стран мира (OК (MК (ИСО 3166) 004-97) 025-2001). Пример:

RU

.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

customs_declaration_number

string, optional

Номер таможенной декларации (от 1 до 32 символов).
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

excise

string, optional

Сумма акциза товара с учетом копеек. Десятичное число с точностью до 2 символов после точки.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

tax_system_code

number, optional

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

phone

string, optional

Телефон пользователя. Указывается в формате ITU-T E.164, например

79000000000

.

email

string, optional

Электронная почта пользователя.

sources

array, optional

Данные о том, с какого магазин и какую сумму нужно удержать для проведения возврата. Необходимо передавать, если вы используете решение ЮKassa для платформ . Сейчас в этом параметре можно передать данные только одного магазина.

Вложенные параметры

account_id

string, required

Идентификатор магазина, для которого вы хотите провести возврат. Выдается ЮKassa, отображается в разделе Продавцы личного кабинета (столбец shopId).

amount

object, required

Сумма возврата.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

platform_fee_amount

object, optional

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

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/refunds \
  -X POST \
  -u <Идентификатор магазина>:<Секретный ключ> \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "amount": {
          "value": "2.00",
          "currency": "RUB"
        },
        "payment_id": "215d8da0-000f-50be-b000-0003308c89be"
      }'

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

{
  "id": "216749f7-0016-50be-b000-078d43a63ae4",
  "status": "succeeded",
  "amount": {
    "value": "1",
    "currency": "RUB"
  },
  "created_at": "2017-10-04T19:27:51.407Z",
  "payment_id": "216749da-000f-50be-b000-096747fad91e"
}

Список возвратов

Запрос позволяет получить список возвратов, отфильтрованный по заданным критериям.

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

Если результатов больше, чем задано в

limit

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

next_cursor

с указателем на следующий фрагмент.

Подробнее о работе со списками

Описание параметров запроса

Параметры запроса

Описание

created_at.gte

string, optional

Фильтр по времени создания: время должно быть больше указанного значения или равно ему («с такого-то момента включительно»). Указывается в формате ISO 8601. Пример:

created_at.gte=2018-07-18T10:51:18.139Z

created_at.gt

string, optional

Фильтр по времени создания: время должно быть больше указанного значения («с такого-то момента, не включая его»). Указывается в формате ISO 8601. Пример:

created_at.gt=2018-07-18T10:51:18.139Z

created_at.lte

string, optional

Фильтр по времени создания: время должно быть меньше указанного значения или равно ему («по такой-то момент включительно»). Указывается в формате ISO 8601. Пример:

created_at.lte=2018-07-18T10:51:18.139Z

created_at.lt

string, optional

Фильтр по времени создания: время должно быть меньше указанного значения («по такой-то момент, не включая его»). Указывается в формате ISO 8601. Пример:

created_at.lt=2018-07-18T10:51:18.139Z

payment_id

string, optional

Фильтр по идентификатору платежа (получить все возвраты по платежу). Пример:

payment_id=1da5c87d-0984-50e8-a7f3-8de646dd9ec9

status

string, optional

Фильтр по статусу возврата. Возможные значения:

pending

— в обработке,

succeeded

— успешно выполнен,

canceled

— отменен. Пример:

status=succeeded

limit

number, optional

Размер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример:

limit=50

Значение по умолчанию:

10

cursor

string, optional

Указатель на следующий фрагмент списка. Пример:

cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15

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

next_cursor

, полученное в ответе на предыдущий запрос. Используется, если в списке больше объектов, чем может поместиться в выдаче (

limit

), и конец выдачи не достигнут. Пример использования

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/refunds \
  -u <Идентификатор магазина>:<Секретный ключ>

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

{
  "type": "list",
  "items": [
    {
      "id": "216749f7-0016-50be-b000-078d43a63ae4",
      "status": "succeeded",
      "amount": {
        "value": "1",
        "currency": "RUB"
      },
      "created_at": "2017-10-04T19:27:51.407Z",
      "payment_id": "216749da-000f-50be-b000-096747fad91e"
    }
  ],
  "next_cursor": "416746f8-0016-50be-b000-078d43a4578"
}

Информация о возврате

Запрос позволяет получить информацию о текущем состоянии возврата по его уникальному идентификатору.

В ответ на запрос придет объект возврата в актуальном статусе.

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/refunds/{refund_id} \
  -u <Идентификатор магазина>:<Секретный ключ>

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

{
  "id": "216749f7-0016-50be-b000-078d43a63ae4",
  "status": "succeeded",
  "amount": {
    "value": "1",
    "currency": "RUB"
  },
  "created_at": "2017-10-04T19:27:51.407Z",
  "payment_id": "216749da-000f-50be-b000-096747fad91e"
}

Чеки

Для тех, кто использует решение ЮKassa для 54-ФЗ

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

cURL

PHP

Python

Объект чека

Объект чека (

Receipt

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

Описание параметров

Параметры

Описание

id

string, required

Идентификатор чека в ЮKassa.

type

string, required

Тип чека в онлайн-кассе: приход (

payment

) или возврат прихода (

refund

).

payment_id

string, optional

Идентификатор платежа, для которого был сформирован чек.

refund_id

string, optional

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

status

string, required

Статус доставки данных для чека в онлайн-кассу (

pending

,

succeeded

или

canceled

).

fiscal_document_number

string, optional

Номер фискального документа.

fiscal_storage_number

string, optional

Номер фискального накопителя в кассовом аппарате.

fiscal_attribute

string, optional

Фискальный признак чека. Формируется фискальным накопителем на основе данных, переданных для регистрации чека.

registered_at

string, optional

Дата и время формирования чека в фискальном накопителе. Указывается в формате ISO 8601.

fiscal_provider_id

string, optional

Идентификатор чека в онлайн-кассе. Присутствует, если чек удалось зарегистрировать.

tax_system_code

number, optional

Система налогообложения магазина. Перечень возможных значений

items

array, required

Список товаров в чеке (не более 100 товаров).

Вложенные параметры

description

string, required

Название товара (не более 128 символов).

quantity

number, required

Количество товара. Максимально возможное значение зависит от модели вашей онлайн-кассы. Формат: десятичное число, дробная часть — три знака или больше (количество знаков зависит от

quantity

в запросе). Дробная часть отделяется точкой. Пример:

5.000

amount

object, required

Цена товара.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

vat_code

number, required

Ставка НДС. Возможные значения — числа от 1 до 6. Подробнее про коды ставок НДС

payment_subject

string, optional

Признак предмета расчета. Перечень возможных значений

payment_mode

string, optional

Признак способа расчета. Перечень возможных значений

supplier

object, optional

Информация о поставщике товара или услуги. Можно передавать, если вы отправляете данные для формирования чека по сценарию Сначала платеж, потом чек .

Вложенные параметры

name

string, optional

Наименование поставщика. Параметр предусмотрен форматом фискальных документов (ФФД) и является обязательным, начиная с версии 1.1.

phone

string, optional

Телефон поставщика. Указывается в формате ITU-T E.164, например

79000000000

. Параметр предусмотрен форматом фискальных документов (ФФД) и является обязательным, начиная с версии 1.1.

inn

string, optional

ИНН поставщика (10 или 12 цифр). Параметр предусмотрен форматом фискальных документов (ФФД) и является обязательным, начиная с версии 1.05.

agent_type

string, optional

Тип посредника, реализующего товар или услугу. Параметр предусмотрен форматом фискальных документов (ФФД) и является обязательным, начиная с версии 1.1. Перечень возможных значений . Можно передавать, если ваша онлайн-касса обновлена до ФФД 1.1 и вы отправляете данные для формирования чека по сценарию Сначала платеж, потом чек

settlements

array, optional

Перечень совершенных расчетов.

Вложенные параметры

type

string, required

Тип расчета. Перечень возможных значений

amount

object, required

Сумма расчета.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

on_behalf_of

string, optional

Идентификатор магазина, от имени которого нужно отправить чек. Выдается ЮKassa. Присутствует, если вы используете решение ЮKassa для платформ .

Пример объекта Receipt

{
  "id": "rt-1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "payment",
  "payment_id": "215d8da0-000f-50be-b000-0003308c89be",
  "status": "succeeded",
  "fiscal_document_number": "3986",
  "fiscal_storage_number": "9288000100115785",
  "fiscal_attribute": "2617603921",
  "registered_at": "2019-05-13T17:56:00.000+03:00",
  "fiscal_provider_id": "fd9e9404-eaca-4000-8ec9-dc228ead2345",
  "tax_system_code": 1,
  "items": [
    {
      "description": "Сapybara",
      "quantity": 5.000,
      "amount": {
        "value": "2500.50",
        "currency": "RUB"
      },
      "vat_code": 2,
      "payment_mode": "full_payment",
      "payment_subject": "commodity"
    }
  ]
}

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

Запрос позволяет передать онлайн-кассе данные для формирования чека зачета предоплаты .

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

Какие сценарии отправки чека существуют

Описание параметров запроса

Параметры запроса

Описание

type

string, required

Тип чека в онлайн-кассе. Возможные значения:

payment

(приход),

refund

(возврат прихода).

payment_id

string, optional

Идентификатор платежа в ЮKassa для отображения информации о чеке в личном кабинете, на платеж не влияет. Обязательный параметр при создании чека прихода (тип чека —

payment

, статус платежа —

waiting_for_capture

или

succeeded

) и при создании чека возврата прихода для отмененного или частично подтвержденного платежа (тип чека —

refund

, статус платежа —

canceled

или

succeeded

).

refund_id

string, optional

Идентификатор возврата в ЮKassa для отображения информации о чеке в личном кабинете. Обязательный параметр при создании чека возврата прихода (если тип чека —

refund

, статус возврата —

succeeded

).

customer

object, required

Информация о пользователе. Необходимо указать как минимум контактные данные: электронную почту (

customer.email

) или номер телефона (

customer.phone

).

Вложенные параметры

full_name

string, optional

Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные. Не более 256 символов.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, АТОЛ Онлайн.

inn

string, optional

ИНН пользователя (10 или 12 цифр).

email

string, optional

Электронная почта пользователя.

phone

string, optional

Телефон пользователя. Указывается в формате ITU-T E.164, например

79000000000

.

items

array, required

Список товаров в чеке (не более 100 товаров).

Вложенные параметры

description

string, required

Название товара (не более 128 символов).

quantity

string, required

Количество товара. Максимально возможное значение зависит от модели вашей онлайн-кассы.

amount

object, required

Цена товара.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

vat_code

number, required

Ставка НДС. Возможные значения — числа от 1 до 6. Подробнее про коды ставок НДС

payment_subject

string, optional

Признак предмета расчета. Перечень возможных значений

payment_mode

string, optional

Признак способа расчета. Перечень возможных значений

product_code

string, optional

Код товара — уникальный номер, который присваивается экземпляру товара при маркировке.
Формат: число в шестнадцатеричном представлении с пробелами. Максимальная длина — 32 байта. Пример:

00 00 00 01 00 21 FA 41 00 23 05 41 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 12 00 AB 00

.
Обязательный параметр, если товар нужно маркировать.

country_of_origin_code

string, optional

Код страны происхождения товара по общероссийскому классификатору стран мира (OК (MК (ИСО 3166) 004-97) 025-2001). Пример:

RU

.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

customs_declaration_number

string, optional

Номер таможенной декларации (от 1 до 32 символов).
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

excise

string, optional

Сумма акциза товара с учетом копеек. Десятичное число с точностью до 2 символов после точки.
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, Кит Инвест.

supplier

object, optional

Информация о поставщике товара или услуги. Можно передавать, если вы отправляете данные для формирования чека по сценарию Сначала платеж, потом чек .

Вложенные параметры

name

string, optional

Наименование поставщика. Параметр предусмотрен форматом фискальных документов (ФФД) и является обязательным, начиная с версии 1.1.

phone

string, optional

Телефон поставщика. Указывается в формате ITU-T E.164, например

79000000000

. Параметр предусмотрен форматом фискальных документов (ФФД) и является обязательным, начиная с версии 1.1.

inn

string, optional

ИНН поставщика (10 или 12 цифр). Параметр предусмотрен форматом фискальных документов (ФФД) и является обязательным, начиная с версии 1.05.

agent_type

string, optional

Тип посредника, реализующего товар или услугу. Параметр предусмотрен форматом фискальных документов (ФФД) и является обязательным, начиная с версии 1.1. Перечень возможных значений . Можно передавать, если ваша онлайн-касса обновлена до ФФД 1.1 и вы отправляете данные для формирования чека по сценарию Сначала платеж, потом чек

tax_system_code

number, optional

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

send

boolean, required

Формирование чека в онлайн-кассе сразу после создания объекта чека. Сейчас можно передать только значение

true

.

settlements

array, required

Перечень совершенных расчетов.

Вложенные параметры

type

string, required

Тип расчета. Перечень возможных значений

amount

object, required

Сумма расчета.

Вложенные параметры

value

string, required

Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например

10.00

. Количество знаков после точки зависит от выбранной валюты.

currency

string, required

Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (

recipient.gateway_id

), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.

on_behalf_of

string, optional

Идентификатор магазина, от имени которого нужно отправить чек. Выдается ЮKassa, отображается в разделе Продавцы личного кабинета (столбец shopId). Необходимо передавать, если вы используете решение ЮKassa для платформ .

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" : "Ivanov Ivan Ivanovich",
          "email" : "email@email.ru",
          "phone" : "79211234567",
          "inn" : "6321341814"
        },
        "payment_id": "24b94598-000f-5000-9000-1b68e7b15f3f",
        "type": "payment",
        "send": "true",
        "items": [
          {
            "description": "Наименование товара 1",
            "quantity": 1.000,
            "amount": {
              "value": "14000.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": "1000.00",
              "currency": "RUB"
            },
            "vat_code": "2",
            "payment_mode": "full_payment",
            "payment_subject": "commodity",
            "country_of_origin_code": "CN",
          },
        ],
        "settlements": [
          {
            "type": "prepayment",
            "amount": {
              "value": "8000.00",
              "currency": "RUB"
            },
          },
          {
            "type": "prepayment",
            "amount": {
              "value": "7000.00",
              "currency": "RUB"
            }
          }
        ]
      }'

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

{
  "id": "rt_1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
  "type": "payment",
  "payment_id": "215d8da0-000f-50be-b000-0003308c89be",
  "status": "pending",
  "items": [
    {
      "description": "Наименование товара 1",
      "quantity": 1.000,
      "amount": {
        "value": "14000.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": "1000.00",
        "currency": "RUB"
      },
      "vat_code": "2",
      "payment_mode": "full_payment",
      "payment_subject": "commodity",
      "country_of_origin_code": "CN"
    }
  ],
  "settlements": [
    {
      "type": "prepayment",
      "amount": {
        "value": "8000.00",
        "currency": "RUB"
      }
    },
    {
      "type": "prepayment",
      "amount": {
        "value": "7000.00",
        "currency": "RUB"
      }
    }
  ],
  "tax_system_code": 1
}

Список чеков

Запрос позволяет получить список чеков, отфильтрованный по заданным критериям. Можно запросить чеки по конкретному платежу, чеки по конкретному возврату или все чеки магазина.

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

Если результатов больше, чем задано в

limit

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

next_cursor

с указателем на следующий фрагмент.

Подробнее о работе со списками

Описание параметров запроса

Параметры запроса

Описание

created_at.gte

string, optional

Фильтр по времени создания: время должно быть больше указанного значения или равно ему («с такого-то момента включительно»). Указывается в формате ISO 8601. Пример:

created_at.gte=2018-07-18T10:51:18.139Z

created_at.gt

string, optional

Фильтр по времени создания: время должно быть больше указанного значения («с такого-то момента, не включая его»). Указывается в формате ISO 8601. Пример:

created_at.gt=2018-07-18T10:51:18.139Z

created_at.lte

string, optional

Фильтр по времени создания: время должно быть меньше указанного значения или равно ему («по такой-то момент включительно»). Указывается в формате ISO 8601. Пример:

created_at.lte=2018-07-18T10:51:18.139Z

created_at.lt

string, optional

Фильтр по времени создания: время должно быть меньше указанного значения («по такой-то момент, не включая его»). Указывается в формате ISO 8601. Пример:

created_at.lt=2018-07-18T10:51:18.139Z

status

string, optional

Фильтр по статусу чека. Возможные значения:

pending

— в обработке,

succeeded

— успешно зарегистрирован,

canceled

— отменен. Пример:

status=succeeded

payment_id

string, optional

Фильтр по идентификатору платежа (получить все чеки для указанного платежа). Пример:

payment_id=1da5c87d-0984-50e8-a7f3-8de646dd9ec9

В запросе можно передать только что-то одно: или идентификатор платежа, или идентификатор возврата.

refund_id

string, optional

Фильтр по идентификатору возврата (получить все чеки для указанного возврата). Пример:

refund_id=1da5c87d-0984-50e8-a7f3-8de646dd9ec9

В запросе можно передать только что-то одно: или идентификатор платежа, или идентификатор возврата.

limit

number, optional

Размер выдачи результатов запроса — количество объектов, передаваемых в ответе. Возможные значения: от 1 до 100. Пример:

limit=50

Значение по умолчанию:

10

cursor

string, optional

Указатель на следующий фрагмент списка. Пример:

cursor=37a5c87d-3984-51e8-a7f3-8de646d39ec15

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

next_cursor

, полученное в ответе на предыдущий запрос. Используется, если в списке больше объектов, чем может поместиться в выдаче (

limit

), и конец выдачи не достигнут. Пример использования

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/receipts \
  -u <Идентификатор магазина>:<Секретный ключ>

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

{
  "type": "list",
  "items": [
    {
      "id": "rt_1da5c87d-0984-50e8-a7f3-8de646dd9ec9",
      "type": "payment",
      "payment_id": "215d8da0-000f-50be-b000-0003308c89be",
      "status": "succeeded",
      "fiscal_document_number": "3986",
      "fiscal_storage_number": "9288000100115785",
      "fiscal_attribute": "2617603921",
      "registered_at": "2019-05-13T17:56:00.000+03:00",
      "fiscal_provider_id": "fd9e9404-eaca-4000-8ec9-dc228ead2345",
      "items": [
        {
          "description": "Сapybara",
          "quantity": 5.000,
          "amount": {
            "value": "2500.50",
            "currency": "RUB"
          },
          "vat_code": 2,
          "payment_mode": "full_payment",
          "payment_subject": "commodity"
        }
      ],
      "tax_system_code": 1
    },
    {
      "id": "rt_2da5c87d-0384-50e8-a7f3-8d5646dd9e10",
      "type": "payment",
      "payment_id": "215d8da0-000f-50be-b000-0003308c89be",
      "status": "pending",
      "items": [
        {
          "description": "Сapybara",
          "quantity": 5.000,
          "amount": {
            "value": "1500.30",
            "currency": "RUB"
          },
          "vat_code": 2,
          "payment_mode": "full_payment",
          "payment_subject": "commodity"
        }
      ],
      "tax_system_code": 1
    },
    {
      "id": "rt_37a5c87d-3984-51e8-a7f3-8de646d39ec15",
      "type": "refund",
      "refund_id": "234d8da0-000f-50be-b000-0003308c89be",
      "status": "pending",
      "items": [
        {
          "description": "Сapybara",
          "quantity": 5.000,
          "amount": {
            "value": "2500.50",
            "currency": "RUB"
          },
          "vat_code": 2,
          "payment_mode": "full_payment",
          "payment_subject": "commodity"
        }
      ],
      "tax_system_code": 1
    }
  ],
  "next_cursor": "rt_67a4g56e-8487-56d4-a7f3-7yu646s78ec48"
}

Информация о чеке

Запрос позволяет получить информацию о текущем состоянии чека по его уникальному идентификатору.

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

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/receipts/{receipt_id} \
  -u <Идентификатор магазина>:<Секретный ключ>

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

{
  "id": "rt-2da5c87d-0384-50e8-a7f3-8d5646dd9e10",
  "type": "payment",
  "status": "succeeded",
  "payment_id": "225d8da0-000f-50be-b000-0003308c89be",
  "fiscal_document_number": "3997",
  "fiscal_storage_number": "9288000100115786",
  "fiscal_attribute": "2617603922",
  "registered_at": "2019-09-18T10:06:42.985Z",
  "fiscal_provider_id": "fd9e9404-eaca-4000-8ec9-dc228ead2346",
  "items": [
    {
      "quantity": 5.000,
      "amount": {
        "value": "1500.30",
        "currency": "RUB"
      },
      "vat_code": 2,
      "description": "Сapybara",
      "payment_mode": "full_payment",
      "payment_subject": "commodity"
    }
  ],
  "tax_system_code": 1,
  "settlements": [
    {
      "type": "cashless",
      "amount": {
        "value": "45.67",
        "currency": "RUB"
      }
    }
  ]
}

Webhooks

Аутентификация только по OAuth-токену. Доступно в рамках API для партнеров

Webhook — это механизм автоматического оповещения вашей системы о событиях, которые происходят с созданными объектами. Например, ЮKassa может сообщить, когда объект платежа, созданный в вашем приложении, перейдет в статус

waiting_for_capture

.

С помощью API вы можете настроить webhook (создать, удалить, просмотреть список созданных) для переданного OAuth-токена.

Подробнее об уведомлениях API ЮKassa

cURL

PHP

Python

Объект Webhook

Объект

Webhook

содержит информацию о подписке на одно событие .

Описание параметров

Параметры

Описание

id

string, required

Идентификатор webhook.

event

string, required

Событие

, о котором уведомляет ЮKassa.

url

string, required

URL, на который ЮKassa отправляет уведомления.

Пример объекта Webhook

{
  "id": "e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "event": "payment.succeeded",
  "url": "https://www.merchant-website.com/notification_url"
}

Создание webhook

Запрос позволяет подписаться на уведомления о событии (например, переход платежа в статус

succeeded

).

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

Если вы хотите получать уведомления о нескольких событиях, вам нужно для каждого из них создать свой webhook. Для каждого OAuth-токена нужно создавать свой набор webhook.

Описание параметров запроса

Параметры запроса

Описание

event

string, required

Событие

, которое вы хотите отслеживать.

url

string, required

URL, на который ЮKassa будет отправлять уведомления.

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/webhooks \
  -X POST \
  -H 'Authorization: Bearer <oauth_token>' \
  -H 'Idempotence-Key: <Ключ идемпотентности>' \
  -H 'Content-Type: application/json' \
  -d '{
        "event": "payment.succeeded",
        "url": "https://www.merchant-website.com/notification_url"
      }'

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

{
  "id": "e44e8088-bd73-43b1-959a-954f3a7d0c54",
  "event": "payment.succeeded",
  "url": "https://www.merchant-website.com/notification_url"
}

Список созданных webhook

Запрос позволяет узнать, какие webhook есть для переданного OAuth-токена.

В ответ на запрос придет актуальный список объектов webhook.

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/webhooks \
  -H 'Authorization: Bearer <oauth_token>'

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

{
  "type": "list",
  "items": [
    {
      "id": "e44e8088-bd73-43b1-959a-954f3a7d0c54",
      "event": "payment.succeeded",
      "url": "https://www.merchant-website.com/notification_url"
    },
    {
      "id": "8d30d343-3441-4af8-9e48-633b8e5e8c21",
      "event": "payment.canceled",
      "url": "https://www.merchant-website.com/notification_url"
    }
  ]
}

Удаление webhook

Запрос позволяет отписаться от уведомлений о событии для переданного OAuth-токена. Чтобы удалить webhook, вам нужно передать в запросе его идентификатор.

В ответ вернется пустое тело.

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/webhooks/{webhook_id} \
  -X DELETE \
  -H 'Authorization: Bearer <oauth_token>' \
  -H 'Content-Type: application/json'

Магазин

Аутентификация только по OAuth-токену. Доступно в рамках API для партнеров

С помощью API вы можете получить справочную информацию о магазине, для которого выдан OAuth-токен.

cURL

PHP

Python

Объект магазина

Объект магазина (

Me

) содержит актуальную информацию о настройках магазина, для которого выдан OAuth-токен. Он приходит в ответ на запрос информации о магазине.

Описание параметров

Параметры

Описание

account_id

string, required

Идентификатор магазина в ЮKassa.

test

boolean, required

Это тестовый магазин .

fiscalization_enabled

boolean, required

В настройках магазина включена отправка чеков в облачную кассу.

payment_methods

array, required

Список способов оплаты , доступных магазину.

Пример объекта Me

{
  "account_id": "123",
  "test": false,
  "fiscalization_enabled": true,
  "payment_methods": [
    "bank_card",
    "yoo_money"
  ]
}

Информация о магазине

Запрос позволяет получить информацию о магазине для переданного OAuth-токена.

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

cURL

PHP

Python

Пример запроса

curl https://api.yookassa.ru/v3/me \
  -H 'Authorization: Bearer <oauth_token>'

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

{
  "account_id": "123",
  "test": false,
  "fiscalization_enabled": true,
  "payment_methods": [
    "bank_card",
    "yoo_money"
  ]
}