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

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

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

Инструкции по интеграции — описание платежных решений, основанных на API ЮKassa, и ссылки на подробные инструкции.
Формат взаимодействия — описание формата запросов, требования к аутентификации запросов и ключу идемпотентнсти, особенности обработки ответов.
Готовые SDK — ссылки на готовые решения для PHP, Python и других языков программирования.
Входящие уведомления — описание работы с входящими уведомлениями (webhook, callback) для отслеживания статусов объектов.

История изменений API ЮKassa

cURL

PHP

Python

Платежи

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

cURL

PHP

Python

Список методов

POST

/payments

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

GET

/payments

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

GET

/payments

/{payment_id}

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

POST

/payments

/{payment_id}

/capture

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

POST

/payments

/{payment_id}

/cancel

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

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

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

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

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

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

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

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 для отправки чеков в налоговую .

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

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

three_d_secure

object, required

Данные о прохождении пользователем аутентификации по 3‑D Secure для подтверждения платежа.

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

applied

boolean, required

Отображение пользователю формы для прохождения аутентификации по 3‑D Secure. Возможные значения:

true
— ЮKassa отобразила пользователю форму, чтобы он мог пройти аутентификацию по 3‑D Secure;
false
— платеж проходил без аутентификации по 3‑D Secure.

transfers

array, optional

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

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

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 в личном кабинете), если не разделяете.

description

string, optional

Описание транзакции (не более 128 символов), которое продавец увидит в личном кабинете ЮKassa. Например: «Заказ маркетплейса №72».

metadata

object, optional

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

deal

object, optional

Данные о сделке, в составе которой проходит платеж. Присутствует, если вы проводите Безопасную сделку .

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

id

string, required

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

settlements

array, required

Данные о распределении денег.

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

type

string, required

Тип операции. Фиксированное значение:

payout

— выплата продавцу.

amount

object, required

Сумма вознаграждения продавца.

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

value

string, required

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

10.00

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

currency

string, required

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

recipient.gateway_id

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

merchant_customer_id

string, optional

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

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

{
  "id": "22e12f66-000f-5000-8000-18db351245c7",
  "status": "waiting_for_capture",
  "paid": true,
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "authorization_details": {
    "rrn": "10000000000",
    "auth_code": "000000",
    "three_d_secure": {
      "applied": true
    }
  },
  "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": "100500",
    "gateway_id": "100700"
  },
  "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

Данные для формирования чека.

Необходимо передавать в этих случаях:

вы компания или ИП, используете решение ЮKassa для оплаты по 54-ФЗ и отправляете данные для формирования чеков по одному из сценариев: Платеж и чек одновременно или Сначала чек, потом платеж ;
вы самозанятый и используете решение ЮKassa для автоотправки чеков .

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

customer

object, optional

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

customer.email

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

customer.phone

).

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

full_name

string, optional

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

inn

string, optional

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

full_name

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

email

string, optional

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

phone

.

phone

string, optional

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

79000000000

. Обязательный параметр, если не передан

email

.

items

array, required

Список товаров в заказе. Для чеков по 54-ФЗ можно передать не более 100 товаров, для чеков самозанятых — не более шести.

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

description

string, required

Название товара (не более 128 символов). Тег в 54 ФЗ — 1030.

amount

object, required

Цена товара (тег в 54 ФЗ — 1079).

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

value

string, required

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

10.00

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

currency

string, required

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

recipient.gateway_id

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

vat_code

number, required

Ставка НДС (тег в 54 ФЗ — 1199).

Для чеков по 54-ФЗ: возможные значения — числа от

1

до

6

. Подробнее про коды ставок НДС

Для чеков самозанятых: фиксированное значение —

1

.

quantity

string, required

Количество товара (тег в 54 ФЗ — 1023).

Для чеков по 54-ФЗ: максимально возможное значение зависит от модели вашей онлайн-кассы.

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

1

.

measure

string, optional

Мера количества предмета расчета (тег в 54 ФЗ — 2108) — единица измерения товара, например штуки, граммы. Обязателен при использовании ФФД 1.2.
Перечень возможных значений

mark_quantity

object, optional

Дробное количество маркированного товара (тег в 54 ФЗ — 1291). Нужно передавать при одновременном выполнении следующих условий:

используется ФФД версии 1.2;
расчет осуществляется за маркированный товар;
поле
measure
имеет значение
piece
.

Пример: вы продаете поштучно карандаши. Они поставляются пачками по 100 штук с одним кодом маркировки. При продаже одного карандаша нужно в

numerator

передать

1

, а в

denominator

—

100

.

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

numerator

integer, required

Числитель — количество продаваемых товаров из одной потребительской упаковки (тег в 54 ФЗ — 1293). Не может превышать

denominator

.

denominator

integer, required

Знаменатель — общее количество товаров в потребительской упаковке (тег в 54 ФЗ — 1294).

payment_subject

string, optional

Признак предмета расчета (тег в 54 ФЗ — 1212) — это то, за что принимается оплата, например товар, услуга. Перечень возможных значений

payment_mode

string, optional

Признак способа расчета (тег в 54 ФЗ — 1214) — отражает тип оплаты и факт передачи товара. Пример: покупатель полностью оплачивает товар и сразу получает его. В этом случае нужно передать значение

full_payment

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

country_of_origin_code

string, optional

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

RU

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

customs_declaration_number

string, optional

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

excise

string, optional

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

product_code

string, optional

Код товара (тег в 54 ФЗ — 1162) — уникальный номер, который присваивается экземпляру товара при маркировке.
Формат: число в шестнадцатеричном представлении с пробелами. Максимальная длина — 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

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

mark_code_info

object, optional

Код товара (тег в 54 ФЗ — 1163). Обязателен при использовании протокола ФФД 1.2, если товар нужно маркировать. Должно быть заполнено хотя бы одно из полей.

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

mark_code_raw

string, optional

Код товара в том виде, в котором он был прочитан сканером (тег в 54 ФЗ — 2000).
Нужно передавать, если пользуетесь онлайн-кассой Orange Data.
Пример:

010460406000590021N4N57RTCBUZTQ\u001d2403054002410161218\u001d1424010191ffd0\u001g92tIAF/YVpU4roQS3M/m4z78yFq0nc/WsSmLeX6QkF/YVWwy5IMYAeiQ91Xa2m/fFSJcOkb2N+uUUtfr4n0mOX0Q==

unknown

string, optional

Нераспознанный код товара (тег в 54 ФЗ — 1300).

ean_8

string, optional

Код товара в формате EAN-8 (тег в 54 ФЗ — 1301).

ean_13

string, optional

Код товара в формате EAN-13 (тег в 54 ФЗ — 1302).

itf_14

string, optional

Код товара в формате ITF-14 (тег в 54 ФЗ — 1303).

gs_10

string, optional

Код товара в формате GS1.0 (тег в 54 ФЗ — 1304).
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, aQsi, Кит Инвест.

gs_1m

string, optional

Код товара в формате GS1.M (тег в 54 ФЗ — 1305).

short

string, optional

Код товара в формате короткого кода маркировки (тег в 54 ФЗ — 1306).

fur

string, optional

Контрольно-идентификационный знак мехового изделия (тег в 54 ФЗ — 1307).

egais_20

string, optional

Код товара в формате ЕГАИС-2.0 (тег в 54 ФЗ — 1308).

egais_30

string, optional

Код товара в формате ЕГАИС-3.0 (тег в 54 ФЗ — 1309).

mark_mode

string, optional

Режим обработки кода маркировки (тег в 54 ФЗ — 2102). Нужно передавать при одновременном выполнении следующих условий:

используется ФФД версии 1.2;
расчет осуществляется за маркированный товар;
используется онлайн-касса Атол Онлайн или BusinessRu.

Должен принимать значение равное «0».

payment_subject_industry_details

array, optional

Отраслевой реквизит предмета расчета (тег в 54 ФЗ — 1260). Нужно передавать, если используете ФФД 1.2.

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

federal_id

string, required

Идентификатор федерального органа исполнительной власти (тег в 54 ФЗ — 1262).

document_date

string, required

Дата документа основания (тег в 54 ФЗ — 1263). Передается в формате ISO 8601

document_number

string, required

Номер нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита» (тег в 54 ФЗ — 1264).

value

string, required

Значение отраслевого реквизита (тег в 54 ФЗ — 1265).

phone

string, optional

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

79000000000

.
Устарел — данные рекомендуется передавать в параметре

receipt.customer.phone

.

email

string, optional

Электронная почта пользователя для отправки чека.
Устарел — данные рекомендуется передавать в параметре

receipt.customer.email

.

tax_system_code

number, optional

Система налогообложения магазина (тег в 54 ФЗ — 1055). Параметр необходим, если вы используете онлайн-кассу Атол Онлайн, обновленную до ФФД 1.2, или у вас несколько систем налогообложения, в остальных случаях не передается.
Перечень возможных значений

receipt_industry_details

array, optional

Отраслевой реквизит чека (тег в 54 ФЗ — 1261). Нужно передавать, если используете ФФД 1.2.

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

federal_id

string, required

Идентификатор федерального органа исполнительной власти (тег в 54 ФЗ — 1262).

document_date

string, required

Дата документа основания (тег в 54 ФЗ — 1263). Передается в формате ISO 8601

document_number

string, required

Номер нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита» (тег в 54 ФЗ — 1264).

value

string, required

Значение отраслевого реквизита (тег в 54 ФЗ — 1265).

receipt_operational_details

object, optional

Операционный реквизит чека (тег в 54 ФЗ — 1270). Нужно передавать, если используете ФФД 1.2.

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

operation_id

integer, required

Идентификатор операции (тег в 54 ФЗ — 1271). Число от 0 до 255.

value

string, required

Данные операции (тег в 54 ФЗ — 1272).

created_at

string, required

Время создания операции (тег в 54 ФЗ — 1273). Указывается по UTC и передается в формате ISO 8601. Пример:

2017-11-03T11:52:31.827Z

recipient

object, optional

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

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

gateway_id

string, required

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

payment_token

string, optional

Одноразовый токен для проведения оплаты, сформированный с помощью Checkout.js или мобильного 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

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

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

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

type

string, required

Значение —

embedded

.

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

locale

string, optional

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

ru_RU

,

en_US

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

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

Имя пассажира. Необходимо использовать латинские буквы, например SERGEI.

last_name

string, required

Фамилия пассажира. Необходимо использовать латинские буквы, например IVANOV.

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

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

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

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 в личном кабинете), если не разделяете.

description

string, optional

Описание транзакции (не более 128 символов), которое продавец увидит в личном кабинете ЮKassa. Например: «Заказ маркетплейса №72».

metadata

object, optional

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

deal

object, optional

Данные о сделке, в составе которой проходит платеж. Необходимо передавать, если вы проводите Безопасную сделку .

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

id

string, required

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

settlements

array, required

Данные о распределении денег.

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

type

string, required

Тип операции. Фиксированное значение:

payout

— выплата продавцу.

amount

object, required

Сумма вознаграждения продавца.

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

value

string, required

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

10.00

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

currency

string, required

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

recipient.gateway_id

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

merchant_customer_id

string, optional

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

Ответ

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

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": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}

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

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

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

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

Параметры

Описание

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

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

Ответ

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

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

limit

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

next_cursor

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

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

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": "100500",
        "gateway_id": "100700"
      },
      "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": "100500",
    "gateway_id": "100700"
  },
  "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

Данные для формирования чека. Необходимо передавать в этих случаях:

вы компания или ИП, используете решение ЮKassa для оплаты по 54-ФЗ и отправляете данные для формирования чеков по одному из сценариев: Платеж и чек одновременно или Сначала чек, потом платеж ;
вы самозанятый и используете решение ЮKassa для автоотправки чеков .

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

customer

object, optional

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

customer.email

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

customer.phone

).

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

full_name

string, optional

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

inn

string, optional

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

full_name

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

email

string, optional

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

phone

.

phone

string, optional

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

79000000000

. Обязательный параметр, если не передан

email

.

items

array, required

Список товаров в заказе. Для чеков по 54-ФЗ можно передать не более 100 товаров, для чеков самозанятых — не более шести.

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

description

string, required

Название товара (не более 128 символов). Тег в 54 ФЗ — 1030.

amount

object, required

Цена товара (тег в 54 ФЗ — 1079).

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

value

string, required

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

10.00

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

currency

string, required

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

recipient.gateway_id

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

vat_code

number, required

Ставка НДС (тег в 54 ФЗ — 1199).

Для чеков по 54-ФЗ: возможные значения — числа от

1

до

6

. Подробнее про коды ставок НДС

Для чеков самозанятых: фиксированное значение —

1

.

quantity

string, required

Количество товара (тег в 54 ФЗ — 1023).

Для чеков по 54-ФЗ: максимально возможное значение зависит от модели вашей онлайн-кассы.

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

1

.

measure

string, optional

Мера количества предмета расчета (тег в 54 ФЗ — 2108) — единица измерения товара, например штуки, граммы. Обязателен при использовании ФФД 1.2.
Перечень возможных значений

mark_quantity

object, optional

Дробное количество маркированного товара (тег в 54 ФЗ — 1291). Нужно передавать при одновременном выполнении следующих условий:

используется ФФД версии 1.2;
расчет осуществляется за маркированный товар;
поле
measure
имеет значение
piece
.

Пример: вы продаете поштучно карандаши. Они поставляются пачками по 100 штук с одним кодом маркировки. При продаже одного карандаша нужно в

numerator

передать

1

, а в

denominator

—

100

.

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

numerator

integer, required

Числитель — количество продаваемых товаров из одной потребительской упаковки (тег в 54 ФЗ — 1293). Не может превышать

denominator

.

denominator

integer, required

Знаменатель — общее количество товаров в потребительской упаковке (тег в 54 ФЗ — 1294).

payment_subject

string, optional

Признак предмета расчета (тег в 54 ФЗ — 1212) — это то, за что принимается оплата, например товар, услуга. Перечень возможных значений

payment_mode

string, optional

Признак способа расчета (тег в 54 ФЗ — 1214) — отражает тип оплаты и факт передачи товара. Пример: покупатель полностью оплачивает товар и сразу получает его. В этом случае нужно передать значение

full_payment

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

country_of_origin_code

string, optional

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

RU

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

customs_declaration_number

string, optional

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

excise

string, optional

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

product_code

string, optional

Код товара (тег в 54 ФЗ — 1162) — уникальный номер, который присваивается экземпляру товара при маркировке.
Формат: число в шестнадцатеричном представлении с пробелами. Максимальная длина — 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

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

mark_code_info

object, optional

Код товара (тег в 54 ФЗ — 1163). Обязателен при использовании протокола ФФД 1.2, если товар нужно маркировать. Должно быть заполнено хотя бы одно из полей.

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

mark_code_raw

string, optional

Код товара в том виде, в котором он был прочитан сканером (тег в 54 ФЗ — 2000).
Нужно передавать, если пользуетесь онлайн-кассой Orange Data.
Пример:

010460406000590021N4N57RTCBUZTQ\u001d2403054002410161218\u001d1424010191ffd0\u001g92tIAF/YVpU4roQS3M/m4z78yFq0nc/WsSmLeX6QkF/YVWwy5IMYAeiQ91Xa2m/fFSJcOkb2N+uUUtfr4n0mOX0Q==

unknown

string, optional

Нераспознанный код товара (тег в 54 ФЗ — 1300).

ean_8

string, optional

Код товара в формате EAN-8 (тег в 54 ФЗ — 1301).

ean_13

string, optional

Код товара в формате EAN-13 (тег в 54 ФЗ — 1302).

itf_14

string, optional

Код товара в формате ITF-14 (тег в 54 ФЗ — 1303).

gs_10

string, optional

Код товара в формате GS1.0 (тег в 54 ФЗ — 1304).
Онлайн-кассы, которые поддерживают этот параметр: Orange Data, aQsi, Кит Инвест.

gs_1m

string, optional

Код товара в формате GS1.M (тег в 54 ФЗ — 1305).

short

string, optional

Код товара в формате короткого кода маркировки (тег в 54 ФЗ — 1306).

fur

string, optional

Контрольно-идентификационный знак мехового изделия (тег в 54 ФЗ — 1307).

egais_20

string, optional

Код товара в формате ЕГАИС-2.0 (тег в 54 ФЗ — 1308).

egais_30

string, optional

Код товара в формате ЕГАИС-3.0 (тег в 54 ФЗ — 1309).

mark_mode

string, optional

Режим обработки кода маркировки (тег в 54 ФЗ — 2102). Нужно передавать при одновременном выполнении следующих условий:

используется ФФД версии 1.2;
расчет осуществляется за маркированный товар;
используется онлайн-касса Атол Онлайн или BusinessRu.

Должен принимать значение равное «0».

payment_subject_industry_details

array, optional

Отраслевой реквизит предмета расчета (тег в 54 ФЗ — 1260). Нужно передавать, если используете ФФД 1.2.

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

federal_id

string, required

Идентификатор федерального органа исполнительной власти (тег в 54 ФЗ — 1262).

document_date

string, required

Дата документа основания (тег в 54 ФЗ — 1263). Передается в формате ISO 8601

document_number

string, required

Номер нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита» (тег в 54 ФЗ — 1264).

value

string, required

Значение отраслевого реквизита (тег в 54 ФЗ — 1265).

phone

string, optional

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

79000000000

.
Устарел — данные рекомендуется передавать в параметре

receipt.customer.phone

.

email

string, optional

Электронная почта пользователя для отправки чека.
Устарел — данные рекомендуется передавать в параметре

receipt.customer.email

.

tax_system_code

number, optional

Система налогообложения магазина (тег в 54 ФЗ — 1055). Параметр необходим, если вы используете онлайн-кассу Атол Онлайн, обновленную до ФФД 1.2, или у вас несколько систем налогообложения, в остальных случаях не передается.
Перечень возможных значений

receipt_industry_details

array, optional

Отраслевой реквизит чека (тег в 54 ФЗ — 1261). Нужно передавать, если используете ФФД 1.2.

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

federal_id

string, required

Идентификатор федерального органа исполнительной власти (тег в 54 ФЗ — 1262).

document_date

string, required

Дата документа основания (тег в 54 ФЗ — 1263). Передается в формате ISO 8601

document_number

string, required

Номер нормативного акта федерального органа исполнительной власти, регламентирующего порядок заполнения реквизита «значение отраслевого реквизита» (тег в 54 ФЗ — 1264).

value

string, required

Значение отраслевого реквизита (тег в 54 ФЗ — 1265).

receipt_operational_details

object, optional

Операционный реквизит чека (тег в 54 ФЗ — 1270). Нужно передавать, если используете ФФД 1.2.

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

operation_id

integer, required

Идентификатор операции (тег в 54 ФЗ — 1271). Число от 0 до 255.

value

string, required

Данные операции (тег в 54 ФЗ — 1272).

created_at

string, required

Время создания операции (тег в 54 ФЗ — 1273). Указывается по UTC и передается в формате ISO 8601. Пример:

2017-11-03T11:52:31.827Z

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

Имя пассажира. Необходимо использовать латинские буквы, например SERGEI.

last_name

string, required

Фамилия пассажира. Необходимо использовать латинские буквы, например IVANOV.

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

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

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

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 в личном кабинете), если не разделяете.

deal

object, optional

Данные о сделке, в составе которой проходит платеж. Необходимо передавать, если вы проводите Безопасную сделку и подтверждаете часть платежа.

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

settlements

object, required

Данные о распределении денег.

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

type

string, required

Тип операции. Фиксированное значение:

payout

— выплата продавцу.

amount

object, required

Сумма вознаграждения продавца.

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

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": "100500",
    "gateway_id": "100700"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}

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

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

waiting_for_capture

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

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

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

Без параметров.

Ответ

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

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": "100500",
    "gateway_id": "100700"
  },
  "refundable": false,
  "test": false
}

Возвраты

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

payment_method

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

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

cURL

PHP

Python

Список методов

POST

/refunds

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

GET

/refunds

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

GET

/refunds

/{refund_id}

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

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

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

Refund

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

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

Параметры

Описание

id

string, required

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

payment_id

string, required

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

status

string, required

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

pending
— возврат создан, но пока еще обрабатывается;
succeeded
— возврат успешно завершен, указанная в запросе сумма переведена на платежное средство пользователя (финальный и неизменяемый статус);
canceled
— возврат отменен, инициатор и причина отмены указаны в объекте
cancellation_details
(финальный и неизменяемый статус).

cancellation_details

object, optional

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

canceled

: кто отменил возврат и по какой причине.

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

party

string, required

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

yoo_money

— ЮKassa.

reason

string, required

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

receipt_registration

string, optional

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

pending
— данные в обработке;
succeeded
— чек успешно зарегистрирован;
canceled
— чек зарегистрировать не удалось, сформируйте чек вручную.

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

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

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

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

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 в личном кабинете), если не разделяете.

deal

object, optional

Данные о сделке, в составе которой проходит возврат. Присутствует, если вы проводите Безопасную сделку .

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

id

string, required

Идентификатор сделки. Берется из возвращаемого платежа.

refund_settlements

array, required

Данные о распределении денег.

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

type

string, required

Тип операции. Фиксированное значение:

payout

— выплата продавцу.

amount

object, required

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

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

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

Данные для формирования чека. Необходимо передавать в этих случаях:

вы компания или ИП, используете решение ЮKassa для оплаты по 54-ФЗ и отправляете данные для формирования чеков по одному из сценариев: Платеж и чек одновременно или Сначала чек, потом платеж