cURL
PHP
Python
 Справочник API Яндекс.Кассы
В справочнике API вы найдете описание всех методов API Яндекс.Кассы. С помощью этого API вы можете работать с онлайн-платежами: отправлять запросы на оплату, сохранять платежную информацию для повторных списаний, совершать возвраты и многое другое.
Подробнее об интеграции по API Яндекс.Кассы 
cURL
PHP
Python
 Платежи
API позволяет создавать, подтверждать, отменять платежи, а также получать информацию о них. Как провести платеж 
cURL
PHP
Python
 Объект платежа
Объект платежа (
Payment
) содержит всю информацию о платеже, актуальную на текущий момент времени. Он формируется при создании платежа и приходит в ответ на любой запрос, связанный с платежами.
Описание параметров
Параметры
Описание
 id
string, required
Идентификатор платежа.
 status
string, required
Статус платежа. Возможные значения:
pending
,
waiting_for_capture
,
succeeded
и
canceled
. Подробнее про жизненный цикл платежа 
 amount
object, required
Сумма платежа. Иногда партнеры Яндекс.Кассы берут с пользователя дополнительную комиссию, которая не входит в эту сумму.
Вложенные параметры
 value
string, required
Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например
10.00
. Количество знаков после точки зависит от выбранной валюты.
 currency
string, required
Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (
recipient.gateway_id
), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.
 description
string, optional
Описание транзакции (не более 128 символов), которое вы увидите в личном кабинете Яндекс.Кассы, а пользователь — при оплате. Например: «Оплата заказа № 72 для user@yandex.ru».
 recipient
object, required
Получатель платежа.
Вложенные параметры
 account_id
string, required
Идентификатор магазина в Яндекс.Кассе.
 gateway_id
string, required
Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта.
 requestor
object, required
Инициатор платежа или возврата. Инициатором может быть магазин, подключенный к Яндекс.Кассе, (
merchant
) или приложение, которому владелец магазина разрешил  совершать операции от своего имени (
third_party_client
).
Вложенные параметры
Инициаторы
Магазин
 type
string, required
Значение —
merchant
.
Тип инициатора.
 account_id
string, required
Идентификатор магазина в Яндекс.Кассе.
 payment_method
object, required
Способ оплаты 
, который был использован для этого платежа.
Вложенные параметры
Способы оплаты
Альфа-Клик
 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
Выбранный способ подтверждения платежа. Присутствует, когда платеж ожидает подтверждения от пользователя. Подробнее о сценариях подтверждения 
Вложенные параметры
Сценарии подтверждения
External
 type
string, optional
Значение —
external
.
Код сценария подтверждения.
 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
). Присутствует, если вы используете решение Яндекс.Кассы для работы по 54-ФЗ .
 metadata
object, optional
Любые дополнительные данные, которые нужны вам для работы с платежами (например, номер заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от Яндекс.Кассы. Ограничения: максимум 16 ключей, имя ключа не больше 32 символов, значение ключа не больше 512 символов.
 cancellation_details
object, optional
Комментарий к статусу
canceled
: кто отменил платеж и по какой причине. Подробнее про неуспешные платежи 
Вложенные параметры
 party
string, required
Участник процесса платежа, который принял решение об отмене транзакции. Может принимать значения
yandex_checkout
,
payment_network
и
merchant
. Подробнее про инициаторов отмены платежа 
 reason
string, required
 authorization_details
object, optional
Данные об авторизации платежа.
Вложенные параметры
 rrn
string, optional
Retrieval Reference Number — уникальный идентификатор транзакции в системе эмитента. Используется при оплате банковской картой.
 auth_code
string, optional
Код авторизации банковской карты. Выдается эмитентом и подтверждает проведение авторизации.
Пример объекта 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"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "requestor": {
    "type": "merchant",
    "account_id": "100001"
  },
  "refundable": false,
  "test": false
}
 Создание платежа
Чтобы принять оплату, необходимо создать объект платежа —
Payment
. Он содержит всю необходимую информацию для проведения оплаты (сумму, валюту и статус). У платежа линейный жизненный цикл, он последовательно переходит из статуса в статус.
В ответ на запрос придет объект платежа в актуальном статусе.
Описание параметров запроса
Параметры запроса
Описание
 amount
object, required
Сумма платежа. Иногда партнеры Яндекс.Кассы берут с пользователя дополнительную комиссию, которая не входит в эту сумму.
Вложенные параметры
 value
string, required
Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например
10.00
. Количество знаков после точки зависит от выбранной валюты.
 currency
string, required
Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (
recipient.gateway_id
), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.
 description
string, optional
Описание транзакции (не более 128 символов), которое вы увидите в личном кабинете Яндекс.Кассы, а пользователь — при оплате. Например: «Оплата заказа № 72 для user@yandex.ru».
 receipt
object, optional
Данные для формирования чека в онлайн-кассе (для соблюдения 54-ФЗ ).
Вложенные параметры
 customer
object, optional
Информация о пользователе. Необходимо указать как минимум контактные данные: электронную почту (
customer.email
) или номер телефона (
customer.phone
).
Вложенные параметры
 full_name
string, optional
Для юрлица — название организации, для ИП и физического лица — ФИО. Если у физлица отсутствует ИНН, в этом же параметре передаются паспортные данные. Не более 256 символов.
 inn
string, optional
ИНН пользователя (10 или 12 цифр). Если у физического лица отсутствует ИНН, необходимо передать паспортные данные в параметре
full_name
.
 email
string, optional
Электронная почта пользователя для отправки чека. Обязательный параметр, если не передан
phone
.
 phone
string, optional
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например
79000000000
. Обязательный параметр, если не передан
email
.
 items
array, required
Список товаров в заказе.
Вложенные параметры
 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
.
 customs_declaration_number
string, optional
Номер таможенной декларации (от 1 до 32 символов).
 excise
string, optional
Сумма акциза товара с учетом копеек. Десятичное число с точностью до 2 символов после точки.
 tax_system_code
number, optional
Система налогообложения магазина. Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается. Подробнее про коды систем налогообложения 
 phone
string, optional
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например
79000000000
.
Устарел — данные рекомендуется передавать в параметре
receipt.customer.phone
.
 email
string, optional
Электронная почта пользователя для отправки чека.
Устарел — данные рекомендуется передавать в параметре
receipt.customer.email
.
 recipient
object, optional
Получатель платежа. Нужен, если вы разделяете потоки платежей в рамках одного аккаунта или создаете платеж в адрес другого аккаунта.
Вложенные параметры
 gateway_id
string, required
Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта.
 payment_token
string, optional
Одноразовый токен для проведения оплаты, сформированный с помощью веб или мобильного SDK .
 payment_method_id
string, optional
 payment_method_data
object, optional
Данные для оплаты конкретным способом  (
payment_method
). Вы можете не передавать этот объект в запросе. В этом случае пользователь будет выбирать способ оплаты на стороне Яндекс.Кассы.
Вложенные параметры
Способы оплаты
Альфа-Клик
 type
string, required
Значение —
alfabank
.
Код способа оплаты.
 login
string, optional
Логин пользователя в Альфа-Клике. Обязателен для сценария External .
 confirmation
object, optional
Данные, необходимые для инициации выбранного сценария подтверждения платежа пользователем. Подробнее о сценариях подтверждения 
Вложенные параметры
Сценарии подтверждения
External
 type
string, required
Значение —
external
.
Код сценария подтверждения.
 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
Любые дополнительные данные, которые нужны вам для работы с платежами (например, номер заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от Яндекс.Кассы. Ограничения: максимум 16 ключей, имя ключа не больше 32 символов, значение ключа не больше 512 символов.
 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.
cURL
PHP
Python
Пример запроса
curl https://payment.yandex.net/api/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://money.yandex.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"
  },
  "requestor": {
    "type": "merchant",
    "account_id": "100001"
  },
  "refundable": false,
  "test": false
}
 Информация о платеже
Запрос позволяет получить информацию о текущем состоянии платежа по его уникальному идентификатору.
В ответ на запрос придет объект платежа в актуальном статусе.
cURL
PHP
Python
Пример запроса
curl https://payment.yandex.net/api/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"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "requestor": {
    "type": "merchant",
    "account_id": "100001"
  },
  "refundable": false,
  "test": false
}
 Подтверждение платежа
Подтверждает вашу готовность принять платеж. После подтверждения платеж перейдет в статус
succeeded
. Это значит, что вы можете выдать товар или оказать услугу пользователю.
Подтвердить можно только платеж в статусе
waiting_for_capture
и только в течение определенного времени (зависит от способа оплаты). Если вы не подтвердите платеж в отведенное время, он автоматически перейдет в статус
canceled
, и деньги вернутся пользователю.
В ответ на запрос придет объект платежа в актуальном статусе.
Описание параметров запроса
Параметры запроса
Описание
 amount
object, optional
Итоговая сумма, которая спишется с пользователя. Для платежей банковской картой или из кошелька в Яндекс.Деньгах можно указать часть исходной суммы, в этом случае остаток вернется пользователю.
Вложенные параметры
 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 символов.
 inn
string, optional
ИНН пользователя (10 или 12 цифр). Если у физического лица отсутствует ИНН, необходимо передать паспортные данные в параметре
full_name
.
 email
string, optional
Электронная почта пользователя для отправки чека. Обязательный параметр, если не передан
phone
.
 phone
string, optional
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например
79000000000
. Обязательный параметр, если не передан
email
.
 items
array, required
Список товаров в заказе.
Вложенные параметры
 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
.
 customs_declaration_number
string, optional
Номер таможенной декларации (от 1 до 32 символов).
 excise
string, optional
Сумма акциза товара с учетом копеек. Десятичное число с точностью до 2 символов после точки.
 tax_system_code
number, optional
Система налогообложения магазина. Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается. Подробнее про коды систем налогообложения 
 phone
string, optional
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например
79000000000
.
Устарел — данные рекомендуется передавать в параметре
receipt.customer.phone
.
 email
string, optional
Электронная почта пользователя для отправки чека.
Устарел — данные рекомендуется передавать в параметре
receipt.customer.email
.
 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.
cURL
PHP
Python
Пример запроса
curl https://payment.yandex.net/api/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"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "requestor": {
    "type": "merchant",
    "account_id": "100001"
  },
  "refundable": true,
  "refunded_amount": {
    "value": "0.00",
    "currency": "RUB"
  },
  "test": false
}
 Отмена платежа
Отменяет платеж, находящийся в статусе
waiting_for_capture
. Отмена платежа значит, что вы не готовы выдать пользователю товар или оказать услугу. Как только вы отменяете платеж, мы начинаем возвращать деньги на счет плательщика. Для платежей банковскими картами или из кошелька в Яндекс.Деньгах отмена происходит мгновенно. Для остальных способов оплаты возврат может занимать до нескольких дней.
В ответ на запрос придет объект платежа в актуальном статусе.
cURL
PHP
Python
Пример запроса
curl https://payment.yandex.net/api/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"
    },
    "title": "Bank card *4444"
  },
  "recipient": {
    "account_id": "100001",
    "gateway_id": "1000001"
  },
  "requestor": {
    "type": "merchant",
    "account_id": "100001"
  },
  "refundable": false,
  "test": false
}
 Возвраты
С помощью API можно возвращать платежи — полностью или частично. Порядок возврата зависит от способа оплаты (
payment_method
) исходного платежа. При оплате банковской картой деньги возвращаются на карту, которая была использована для проведения платежа. Как проводить возвраты 
Часть способов оплаты (например, наличные) не поддерживают возвраты. Какие платежи можно вернуть 
cURL
PHP
Python
 Объект возврата
Объект возврата (
Refund
) содержит актуальную информацию о возврате успешного платежа. Он приходит в ответ на любой запрос, связанный с возвратами.
Описание параметров
Параметры
Описание
 id
string, required
Идентификатор возврата платежа в Яндекс.Кассе.
 payment_id
string, required
Идентификатор платежа.
 requestor
object, required
Инициатор платежа или возврата. Инициатором может быть магазин, подключенный к Яндекс.Кассе, (
merchant
) или приложение, которому владелец магазина разрешил  совершать операции от своего имени (
third_party_client
).
Вложенные параметры
Инициаторы
Магазин
 type
string, required
Значение —
merchant
.
Тип инициатора.
 account_id
string, required
Идентификатор магазина в Яндекс.Кассе.
 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
Основание для возврата денег пользователю.
Пример объекта 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",
  "requestor": {
    "type": "merchant",
    "account_id": "100001"
  }
}
 Создание возврата
Создает объект возврата —
Refund
. Возвращает успешно завершенный платеж по уникальному идентификатору этого платежа. Создание возврата возможно только для платежей в статусе
succeeded
. Комиссии за проведение возврата нет. Комиссия, которую Яндекс.Касса берёт за проведение исходного платежа, не возвращается.
В ответ на запрос придет объект возврата в актуальном статусе.
Описание параметров запроса
Параметры запроса
Описание
 payment_id
string, required
Идентификатор платежа.
 amount
object, optional
Сумма, которую нужно вернуть пользователю.
Вложенные параметры
 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 символов.
 inn
string, optional
ИНН пользователя (10 или 12 цифр). Если у физического лица отсутствует ИНН, необходимо передать паспортные данные в параметре
full_name
.
 email
string, optional
Электронная почта пользователя для отправки чека. Обязательный параметр, если не передан
phone
.
 phone
string, optional
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например
79000000000
. Обязательный параметр, если не передан
email
.
 items
array, required
Список товаров в заказе.
Вложенные параметры
 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
.
 customs_declaration_number
string, optional
Номер таможенной декларации (от 1 до 32 символов).
 excise
string, optional
Сумма акциза товара с учетом копеек. Десятичное число с точностью до 2 символов после точки.
 tax_system_code
number, optional
Система налогообложения магазина. Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается. Подробнее про коды систем налогообложения 
 phone
string, optional
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например
79000000000
.
Устарел — данные рекомендуется передавать в параметре
receipt.customer.phone
.
 email
string, optional
Электронная почта пользователя для отправки чека.
Устарел — данные рекомендуется передавать в параметре
receipt.customer.email
.
cURL
PHP
Python
Пример запроса
curl https://payment.yandex.net/api/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",
  "requestor": {
    "type": "merchant",
    "account_id": "100001"
  }
}
 Информация о возврате
Запрос позволяет получить информацию о текущем состоянии возврата по его уникальному идентификатору.
В ответ на запрос придет объект возврата в актуальном статусе.
cURL
PHP
Python
Пример запроса
curl https://payment.yandex.net/api/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",
  "requestor": {
    "type": "merchant",
    "account_id": "100001"
  }
}
 Чеки
Для тех, кто использует решение Яндекс.Кассы для 54-ФЗ 
С помощью API можно получать информацию о чеках, для которых вы отправили данные через Яндекс.Кассу.
cURL
PHP
Python
 Объект чека
Объект чека (
Receipt
) содержит актуальную информацию о чеке, созданном при платеже или возврате.
Описание параметров
Параметры
Описание
 id
string, required
Идентификатор чека в Яндекс.Кассе.
 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
Список товаров в чеке.
Вложенные параметры
 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
Признак способа расчета. Перечень возможных значений 
Пример объекта 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,
      "amount": {
        "value": "2500.50",
        "currency": "RUB"
      },
      "vat_code": 2,
      "payment_mode": "full_payment",
      "payment_subject": "commodity"
    }
  ]
}
 Список чеков
Запрос позволяет узнать, какие чеки были сформированы для платежа или возврата и их статус.
В запросе необходимо передать что-то одно: или идентификатор платежа, или идентификатор возврата.
В ответ на запрос вернется список чеков.
Описание параметров запроса
Параметры запроса
Описание
 payment_id
string, optional
Идентификатор платежа, для которого запрашиваются чеки.
Обязательный параметр, если не передан
refund_id
.
 refund_id
string, optional
Идентификатор возврата, для которого запрашиваются чеки.
Обязательный параметр, если не передан
payment_id
.
cURL
PHP
Python
Пример запроса
curl https://payment.yandex.net/api/v3/receipts?payment_id=<payment_id> \
  -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,
          "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": "225d8da0-000f-50be-b000-0003308c89be",
      "status": "pending",
      "items": [
        {
          "description": "Сapybara",
          "quantity": 5,
          "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,
          "amount": {
            "value": "2500.50",
            "currency": "RUB"
          },
          "vat_code": 2,
          "payment_mode": "full_payment",
          "payment_subject": "commodity"
        }
      ],
      "tax_system_code": 1
    }
  ]
}
 Webhooks
Аутентификация только по OAuth-токену. Доступно в рамках API для партнеров 
Webhook — это механизм автоматического оповещения вашей системы о событиях, которые происходят с созданными объектами. Например, Яндекс.Касса может сообщить, когда объект платежа, созданный в вашем приложении, перейдет в статус
waiting_for_capture
.
С помощью API вы можете настроить webhook (создать, удалить, просмотреть список созданных) для переданного OAuth-токена.
Подробнее об уведомлениях API Яндекс.Кассы
cURL
PHP
Python
 Объект Webhook
Объект
Webhook
содержит информацию о подписке на одно событие .
Описание параметров
Параметры
Описание
 id
string, required
Идентификатор webhook.
 event
string, required
Событие 
, о котором уведомляет Яндекс.Касса.
 url
string, required
URL, на который Яндекс.Касса отправляет уведомления.
Пример объекта 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, на который Яндекс.Касса будет отправлять уведомления.
cURL
PHP
Python
Пример запроса
curl https://payment.yandex.net/api/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://payment.yandex.net/api/v3/webhooks \
  -H 'Authorization: Bearer <oauth_token>'
Пример тела ответа
{
  "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://payment.yandex.net/api/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
Идентификатор магазина в Яндекс.Кассе.
 test
boolean, required
 fiscalization_enabled
boolean, required
В настройках магазина включена отправка чеков  в облачную кассу.
Пример объекта Me
{
  "account_id": "123",
  "test": false,
  "fiscalization_enabled": true
}
 Информация о магазине
Запрос позволяет получить информацию о магазине для переданного OAuth-токена.
В ответ на запрос придет объект магазина.
cURL
PHP
Python
Пример запроса
curl https://payment.yandex.net/api/v3/me \
  -H 'Authorization: Bearer <oauth_token>'
Пример тела ответа
{
  "account_id": "123",
  "test": false,
  "fiscalization_enabled": true
}