NAV Navbar
API Яндекс.Кассы

Использование API

API endpoint

https://payment.yandex.net/api/v3/

Яндекс.Касса — универсальное решение для работы с онлайн-платежами. API Яндекс.Кассы построено на REST-принципах, работает с реальными объектами и обладает предсказуемым поведением. С помощью этого API вы можете отправлять запросы на оплату, сохранять платежную информацию для повторных списаний, совершать возвраты и многое другое.

API в качестве основного протокола использует HTTP, а значит, подходит для разработки на любом языке программирования, который умеет работать с HTTP-библиотеками (cURL и другими). Для аутентификации используется Basic Auth, поэтому вы можете сделать свой первый запрос прямо из браузера.

API поддерживает POST и GET-запросы. POST-запросы используют JSON-аргументы, GET-запросы работают со строками запросов. API всегда возвращает ответ в формате JSON, независимо от типа запроса.

Аутентификация

Пример запроса с аутентификацией

curl https://payment.yandex.net/api/v3/payments/{payment_id} \
          -u <Идентификатор магазина>:<Секретный ключ>
<?php
  use YandexCheckout\Client;

  $client = new Client();
  $client->setAuth('Идентификатор магазина', 'Секретный ключ');
?>

from yandex_checkout import Configuration

Configuration.account_id = <Идентификатор магазина>
Configuration.secret_key = <Секретный ключ>

Для аутентификации запросов используется HTTP Basic Auth. В заголовках запросов необходимо передавать:

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

Идемпотентность

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

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

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

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

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

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"
      }'
<?php
  $idempotenceKey = uniqid('', true);
  $response = $client->createRefund(
      array(
          'payment_id' => '215d8da0-000f-50be-b000-0003308c89be',
          'amount' => array(
              'value' => '2.00',
              'currency' => 'RUB',
          ),
      ),
      $idempotenceKey
  );
?>
from yandex_checkout import Refund
import uuid

idempotence_key = str(uuid.uuid4())
refund = Refund.create({
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "payment_id": "215d8da0-000f-50be-b000-0003308c89be"
}, idempotence_key)

Для обеспечения идемпотентности POST-запросов используется заголовок Idempotence-Key (или ключ идемпотентности).

Как это работает:

В заголовке Idempotence-Key можно передавать любое значение, уникальное для этой операции на вашей стороне. Мы рекомендуем использовать V4 UUID.

Яндекс.Касса обеспечивает идемпотентность в течение 24 часов после первого запроса, потом повторный запрос будет обработан как новый.

Ошибки

Пример тела ответа ошибки

  {
    "type": "error",
    "id": "ab5a11cd-13cc-4e33-af8b-75a74e18dd09",
    "code": "invalid_request",
    "description": "Idempotence key duplicated",
    "parameter": "Idempotence-Key"
  }

Если в процессе обработки запроса произойдет ошибка, API вернет объект ошибки и стандартный HTTP-код.

HTTP-код Описание Код ошибки
200 Успешный запрос.
400 Неправильный запрос. Чаще всего этот статус выдается из-за нарушения правил взаимодействия с API. invalid_request, not_supported
401 Неверный идентификатор вашего аккаунта в Яндекс.Кассе или секретный ключ (имя пользователя и пароль при аутентификации). invalid_credentials
403 Секретный ключ верный, но не хватает прав для совершения операции. forbidden
404 Ресурс не найден. not_found
429 Превышен лимит запросов в единицу времени. Попробуйте снизить интенсивность запросов (можно ориентироваться на поле retry_after — в нем указано количество миллисекунд, через которое стоит повторить запрос). too_many_requests
500 На стороне Яндекс.Кассы что-то пошло не так. internal_server_error

Инструменты

Инструменты для разработчиков созданы, чтобы помочь вам быстрее интегрироваться с API Яндекс.Кассы.

Официальные библиотеки:

Библиотеки, разработанные сообществом:

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

19 ноября 2018

Яндекс.Касса теперь поддерживает ФФД 1.05: добавлена возможность при создании платежа передавать для чека параметры payment_mode (признак способа расчета) и payment_subject (признак предмета расчета).

15 октября 2018

Добавлена возможность создать платеж с новым способом оплаты b2b_sberbank (Сбербанк Бизнес Онлайн).

12 сентября 2018

Яндекс.Касса больше не возвращает HTTP-код 202 («запрос обрабатывается») — в ответ придет либо «успех», либо «неудача».

7 сентября 2018

Добавлен способ оплаты psb (интернет-банк Промсвязьбанка) в объект Payment. Этот способ оплаты пользователь может выбрать только на странице Яндекс.Кассы.

31 июля 2018

Добавлена возможность при создании платежа задать язык, на котором пользователю будет выводиться информация для подтверждения оплаты (параметр locale в объекте confirmation).

20 июля 2018

Добавлен объект authorization_details (данные об авторизации платежа) в объект Payment.

17 июля 2018

Добавлена возможность создать платеж с новым способом оплаты google_pay (Google Pay).

4 июня 2018

Добавлен объект cancellation_details (комментарий к отмене платежа) в объект Payment.

17 апреля 2018

Добавлена возможность создать платеж с новым способом оплаты installments («Заплатить по частям»).

10 апреля 2018

Добавлен параметр first6 (BIN номера банковской карты, первые 6 цифр) в объект card.

4 апреля 2018

Добавлена возможность при создании платежа передать длинную запись для оплаты авиабилетов (объект airline).

15 января 2017

Добавлен признак test в объект Payment.

30 ноября 2017

Добавлен параметр description в объект Payment.

22 ноября 2017

30 октября 2017

Добавлен параметр expires_at в объект Payment.

15 октября 2017

Запуск API Яндекс.Кассы.

Платежи

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

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

Пример объекта 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"
  },
  "test": false
}

Объект платежа (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
Описание транзакции, которое вы увидите в личном кабинете Яндекс.Кассы, а пользователь — при оплате. Например: «Оплата заказа № 72 для user@yandex.ru».
recipient
object
Получатель платежа. Нужен, если вы разделяете потоки платежей в рамках одного аккаунта или создаете платеж в адрес другого аккаунта.
gateway_id
string
required
Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта.
payment_method
object
required
Способ оплаты, который был использован для этого платежа.
string
required
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
login
string
required
Логин пользователя в Альфа-Клике (привязанный телефон или дополнительный логин).
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
payment_purpose
string
required
Назначение платежа (не больше 210 символов).
vat_data
object
required
Данные о налоге на добавленную стоимость (НДС).
string
required
Тип объекта.
Тип объекта.
rate
string
required
Налоговая ставка (в процентах). Возможные значения: 7, 10 и 18.
amount
object
required
Сумма НДС.
value
string
required
Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например 10.00. Количество знаков после точки зависит от выбранной валюты.
currency
string
required
Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.
payer_bank_details
object
required
Банковские реквизиты плательщика (юридического лица или ИП).
full_name
string
required
Полное наименование организации.
short_name
string
required
Сокращенное наименование организации.
address
string
required
Адрес организации.
inn
string
required
Индивидуальный налоговый номер (ИНН) организации.
kpp
string
required
Код причины постановки на учет (КПП) организации.
bank_name
string
required
Наименование банка организации.
bank_branch
string
required
Отделение банка организации.
bank_bik
string
required
Банковский идентификационный код (БИК) банка организации.
account
string
required
Номер счета организации.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
card
object
Данные банковской карты.
first6
string
required
Первые 6 цифр номера карты (BIN).
last4
string
required
Последние 4 цифры номера карты.
expiry_year
string
required
Срок действия, год, YYYY.
expiry_month
string
required
Срок действия, месяц, MM.
card_type
string
required
Тип банковской карты. Возможные значения: MasterCard (для карт Mastercard и Maestro), Visa (для карт Visa и Visa Electron), Mir, UnionPay, JCB, AmericanExpress, DinersClub и Unknown.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
phone
string
Телефон пользователя, на который зарегистрирован аккаунт в Сбербанке Онлайн. Необходим для подтверждения оплаты по смс (сценарий подтверждения external). Указывается в формате ITU-T E.164, например 79000000000.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
id
string
required
Идентификатор способа оплаты.
saved
boolean
required
С помощью сохраненного способа оплаты можно проводить безакцептные списания.
title
string
Название способа оплаты.
account_number
string
Номер кошелька в Яндекс.Деньгах, из которого заплатил пользователь.
captured_at
string
Время подтверждения платежа. Указывается по UTC и передается в формате ISO 8601.
created_at
string
required
Время создания заказа. Указывается по UTC и передается в формате ISO 8601. Пример: 2017-11-03T11:52:31.827Z
expires_at
string
Время, до которого вы можете бесплатно отменить или подтвердить платеж. В указанное время платеж в статусе waiting_for_capture будет автоматически отменен. Указывается по UTC и передается в формате ISO 8601. Пример: 2017-11-03T11:52:31.827Z
confirmation
object
Выбранный способ подтверждения платежа. Присутствует, когда платеж ожидает подтверждения от пользователя. Подробнее про сценарии подтверждения
string
required
Тип объекта external. Сценарий, при котором необходимо подождать, пока пользователь самостоятельно подтвердит платеж в стороннем сервисе. Например, пользователь подтверждает платеж ответом на смс или в приложении партнера.
Тип объекта redirect. Сценарий, при котором необходимо отправить пользователя на веб-страницу Яндекс.Кассы для подтверждения платежа.
enforce
boolean
Запрос на проведение платежа с аутентификацией по 3-D Secure. Будет работать, если оплату банковской картой вы по умолчанию принимаете без подтверждения платежа пользователем. В остальных случаях аутентификацией по 3-D Secure будет управлять Яндекс.Касса. Если хотите принимать платежи без дополнительного подтверждения пользователем, напишите вашему менеджеру Яндекс.Кассы.
return_url
string
URL, на который вернется пользователь после подтверждения или отмены платежа на веб-странице.
confirmation_url
string
required
URL, на который необходимо перенаправить пользователя для подтверждения оплаты.
test
boolean
required
Признак тестовой операции.
refunded_amount
object
Сумма, которая вернулась пользователю. Присутствует, если у этого платежа есть успешные возвраты.
value
string
required
Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например 10.00. Количество знаков после точки зависит от выбранной валюты.
currency
string
required
Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.
paid
boolean
required
Признак оплаты заказа.
receipt_registration
string
Статус доставки данных для чека в онлайн-кассу (pending, succeeded или canceled). Присутствует, если вы используете решение Яндекс.Кассы для работы по 54-ФЗ.
metadata
object
Любые дополнительные данные, которые нужны вам для работы с платежами (например, номер заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от Яндекс.Кассы. Ограничения: максимум 16 ключей, имя ключа не больше 32 символов, значение ключа не больше 512 символов.
cancellation_details
object
Комментарий к статусу canceled: кто отменил платеж и по какой причине. Подробнее про отмененные платежи
party
string
required
Участник процесса платежа, который принял решение об отмене транзакции. Может принимать значения yandex_checkout, payment_network и merchant. Подробнее про инициаторов отмены платежа
reason
string
required
authorization_details
object
Данные об авторизации платежа.
rrn
string
Retrieval Reference Number — уникальный идентификатор транзакции в системе эмитента. Используется при оплате банковской картой.
auth_code
string
Код авторизации банковской карты. Выдается эмитентом и подтверждает проведение авторизации.

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

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

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"
      }'

<?php
  $idempotenceKey = uniqid('', true);
  $response = $client->createPayment(
      array(
          'amount' => array(
              'value' => '2.00',
              'currency' => 'RUB',
          ),
          'payment_method_data' => array(
              'type' => 'bank_card',
          ),
          'confirmation' => array(
              'type' => 'redirect',
              'return_url' => 'https://www.merchant-website.com/return_url',
          ),
          'description' => 'Заказ №72',
      ),
      $idempotenceKey
  );
?>

from yandex_checkout import Payment
import uuid

idempotence_key = str(uuid.uuid4())
payment = Payment.create({
    "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"
}, idempotence_key)

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

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

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

{
  "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
  },
  "test": false
}

Параметры запроса
amount
object
required
Сумма платежа. Иногда партнеры Яндекс.Кассы берут с пользователя дополнительную комиссию, которая не входит в эту сумму.
value
string
required
Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например 10.00. Количество знаков после точки зависит от выбранной валюты.
currency
string
required
Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.
description
string
Описание транзакции, которое вы увидите в личном кабинете Яндекс.Кассы, а пользователь — при оплате. Например: «Оплата заказа № 72 для user@yandex.ru».
receipt
object
Данные для формирования чека в онлайн-кассе (для соблюдения 54-ФЗ). Необходимо указать что-то одно — телефон пользователя (phone) или его электронную почту (email).
items
array
required
Список товаров в заказе.
description
string
required
Название товара.
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
Признак предмета расчета. Перечень возможных значений
payment_mode
string
Признак способа расчета. Перечень возможных значений
tax_system_code
number
Система налогообложения магазина. Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается. Подробнее про коды налогообложения.
phone
string
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например 79000000000.
email
string
Электронная почта пользователя для отправки чека.
recipient
object
Получатель платежа. Нужен, если вы разделяете потоки платежей в рамках одного аккаунта или создаете платеж в адрес другого аккаунта.
gateway_id
string
required
Идентификатор субаккаунта. Используется для разделения потоков платежей в рамках одного аккаунта.
payment_token
string
Одноразовый токен для проведения оплаты, сформированный с помощью клиентской библиотеки (YandexCheckout.js, mSDK).
payment_method_id
string
Идентификатор сохраненного способа оплаты.
payment_method_data
object
Данные для оплаты конкретным способом (payment_method). Вы можете не передавать этот объект в запросе. В этом случае пользователь будет выбирать способ оплаты на стороне Яндекс.Кассы.
string
required
Тип объекта.
Тип объекта
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта.
Тип объекта
login
string
required
Логин пользователя в Альфа-Клике.
payment_data
string
required
Содержимое поля paymentData из объекта PKPaymentToken (платежный токен Apple Pay). Приходит в формате Base64.
payment_purpose
string
required
Назначение платежа (не больше 210 символов).
vat_data
object
required
Данные о налоге на добавленную стоимость (НДС).
string
required
Тип объекта.
Тип объекта.
rate
string
required
Налоговая ставка (в процентах). Возможные значения: 7, 10 и 18.
amount
object
required
Сумма НДС.
value
string
required
Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например 10.00. Количество знаков после точки зависит от выбранной валюты.
currency
string
required
Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.
card
object
Данные банковской карты (необходимы, если вы собираете данные карты пользователей на своей стороне).
number
string
required
Номер банковской карты.
expiry_year
string
required
Срок действия, год, YYYY.
expiry_month
string
required
Срок действия, месяц, MM.
csc
string
Код CVC2 или CVV2, 3 или 4 символа, печатается на обратной стороне карты.
cardholder
string
Имя владельца карты.
phone
string
Телефон пользователя, на который придет смс с кодом платежа (для внесения наличных). Указывается в формате ITU-T E.164, например 79000000000. Поле можно оставить пустым: пользователь сможет заполнить его при оплате на стороне Яндекс.Кассы.
payment_method_token
string
required
Криптограмма Payment Token Cryptography для проведения оплаты через Google Pay. Чтобы ее получить, необходимо вызвать метод PaymentData.getPaymentMethodToken().getToken() в мобильном приложении на устройстве пользователя.
google_transaction_id
string
required
Уникальный идентификатор транзакции, выданный Google. Чтобы его получить, необходимо вызвать метод PaymentData.getGoogleTransactionId() в мобильном приложении на устройстве пользователя.
phone
string
required
Телефон, с баланса которого осуществляется платеж. Указывается в формате ITU-T E.164, например 79000000000.
phone
string
required
Телефон, на который зарегистрирован аккаунт в QIWI. Указывается в формате ITU-T E.164, например 79000000000.
phone
string
Телефон пользователя, на который зарегистрирован аккаунт в Сбербанке Онлайн. Необходим для подтверждения оплаты по смс (сценарий подтверждения external). Указывается в формате ITU-T E.164, например 79000000000.
confirmation
object
Данные, необходимые для инициации выбранного сценария подтверждения платежа пользователем. Подробнее про сценарии подтверждения
string
required
Тип объекта external. Сценарий, при котором необходимо подождать, пока пользователь самостоятельно подтвердит платеж в стороннем сервисе. Например, пользователь подтверждает платеж ответом на смс или в приложении партнера.
Тип объекта redirect. Сценарий, при котором необходимо отправить пользователя на веб-страницу Яндекс.Кассы для подтверждения платежа.
locale
string
Язык интерфейса, писем и смс, которые будет видеть или получать пользователь. Формат соответствует ISO/IEC 15897. Возможные значения: ru_RU, en_US.
locale
string
Язык интерфейса, писем и смс, которые будет видеть или получать пользователь. Формат соответствует ISO/IEC 15897. Возможные значения: ru_RU, en_US.
enforce
boolean
Запрос на проведение платежа с аутентификацией по 3-D Secure. Будет работать, если оплату банковской картой вы по умолчанию принимаете без подтверждения платежа пользователем. В остальных случаях аутентификацией по 3-D Secure будет управлять Яндекс.Касса. Если хотите принимать платежи без дополнительного подтверждения пользователем, напишите вашему менеджеру Яндекс.Кассы.
return_url
string
required
URL, на который вернется пользователь после подтверждения или отмены платежа на веб-странице.
save_payment_method
boolean
Сохранение платежных данных (с их помощью можно проводить повторные безакцептные списания). Значение true инициирует создание многоразового payment_method.
capture
boolean
Автоматический прием поступившего платежа.
client_ip
string
IPv4 или IPv6-адрес пользователя. Если не указан, используется IP-адрес TCP-подключения.
metadata
object
Любые дополнительные данные, которые нужны вам для работы с платежами (например, номер заказа). Передаются в виде набора пар «ключ-значение» и возвращаются в ответе от Яндекс.Кассы. Ограничения: максимум 16 ключей, имя ключа не больше 32 символов, значение ключа не больше 512 символов.
airline
object
Объект с данными для продажи авиабилетов. Используется только для платежей банковской картой.
booking_reference
string
Номер бронирования. Обязателен на этапе создания платежа.
ticket_number
string
Уникальный номер билета. Обязателен на этапе подтверждения платежа.
passengers
array
required
Список пассажиров (обязательно должен быть хотя бы 1 пассажир, максимум — 4).
first_name
string
required
Имя пассажира.
last_name
string
required
Фамилия пассажира.
legs
array
required
Список перелетов (обязательно должен быть хотя бы 1 перелет, максимум — 4).
departure_airport
string
required
Код аэропорта вылета по справочнику IATA, например LED.
destination_airport
string
required
Код аэропорта прилета по справочнику IATA, например AMS.
departure_date
string
required
Дата вылета в формате YYYY-MM-DD ISO 8601:2004.

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

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

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

<?php
  $paymentId = '215d8da0-000f-50be-b000-0003308c89be';
  $payment = $client->getPaymentInfo($paymentId);
?>

from yandex_checkout import Payment

payment_id = '215d8da0-000f-50be-b000-0003308c89be'
payment = Payment.find_one(payment_id)

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

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

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

{
  "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"
  },
  "test": false
}

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

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

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"
        }
      }'

<?php
  $paymentId = '215d8da0-000f-50be-b000-0003308c89be';
  $idempotenceKey = uniqid('', true);
  $response = $client->capturePayment(
      array(
          'amount' => array(
              'value' => '2.00',
              'currency' => 'RUB',
          ),
      ),
      $paymentId,
      $idempotenceKey
  );
?>

from yandex_checkout import Payment
import uuid

payment_id = '215d8da0-000f-50be-b000-0003308c89be'
idempotence_key = str(uuid.uuid4())
response = Payment.capture(
  payment_id,
  {
    "amount": {
      "value": "2.00",
      "currency": "RUB"
    }
  },
  idempotence_key
)

Подтверждает вашу готовность принять платеж. Платеж можно подтвердить, только если он находится в статусе waiting_for_capture. Если платеж подтвержден успешно — значит, оплата прошла, и вы можете выдать товар или оказать услугу пользователю. На следующий день после подтверждения платеж попадет в реестр, и Яндекс.Касса переведет деньги на ваш расчетный счет. Если вы не подтверждаете платеж до момента, указанного в expires_at, по умолчанию он отменяется, а деньги возвращаются пользователю. При оплате банковской картой у вас есть 7 дней на подтверждение платежа, при оплате другими способами — 2 часа. Подробнее о подтверждении и отмене платежей

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

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

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

Параметры запроса
amount
object
Итоговая сумма, которая спишется с пользователя. Можно указать часть исходной суммы, в этом случае остаток вернется пользователю.
value
string
required
Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например 10.00. Количество знаков после точки зависит от выбранной валюты.
currency
string
required
Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.
receipt
object
Данные для формирования чека в онлайн-кассе (для соблюдения 54-ФЗ). Необходимо указать что-то одно — телефон пользователя (phone) или его электронную почту (email).
items
array
required
Список товаров в заказе.
description
string
required
Название товара.
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
Признак предмета расчета. Перечень возможных значений
payment_mode
string
Признак способа расчета. Перечень возможных значений
tax_system_code
number
Система налогообложения магазина. Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается. Подробнее про коды налогообложения.
phone
string
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например 79000000000.
email
string
Электронная почта пользователя для отправки чека.
airline
object
Объект с данными для продажи авиабилетов. Используется только для платежей банковской картой.
booking_reference
string
Номер бронирования. Обязателен на этапе создания платежа.
ticket_number
string
Уникальный номер билета. Обязателен на этапе подтверждения платежа.
passengers
array
required
Список пассажиров (обязательно должен быть хотя бы 1 пассажир, максимум — 4).
first_name
string
required
Имя пассажира.
last_name
string
required
Фамилия пассажира.
legs
array
required
Список перелетов (обязательно должен быть хотя бы 1 перелет, максимум — 4).
departure_airport
string
required
Код аэропорта вылета по справочнику IATA, например LED.
destination_airport
string
required
Код аэропорта прилета по справочнику IATA, например AMS.
departure_date
string
required
Дата вылета в формате YYYY-MM-DD ISO 8601:2004.

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

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

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

<?php
  $paymentId = '215d8da0-000f-50be-b000-0003308c89be';
  $idempotenceKey = uniqid('', true);

  $response = $client->cancelPayment(
      $paymentId,
      $idempotenceKey
  );
?>

from yandex_checkout import Payment
import uuid

payment_id = '215d8da0-000f-50be-b000-0003308c89be'
idempotence_key = str(uuid.uuid4())
response = Payment.cancel(
  payment_id,
  idempotence_key
)

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

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

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

{
  "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"
  },
  "test": false
}

Возвраты

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

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

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

Пример объекта 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"
}

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

Параметры
id
string
required
Идентификатор возврата платежа в Яндекс.Кассе.
payment_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 в личном кабинете), если не разделяете.
receipt_registration
string
Статус доставки данных для чека в онлайн-кассу (pending, succeeded или canceled). Присутствует, если вы используете решение Яндекс.Кассы для работы по 54-ФЗ.
description
string
Основание для возврата денег пользователю.

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

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

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"
      }'

<?php
  $idempotenceKey = uniqid('', true);
  $response = $client->createRefund(
      array(
          'payment_id' => '215d8da0-000f-50be-b000-0003308c89be',
          'amount' => array(
              'value' => '2.00',
              'currency' => 'RUB',
          ),
      ),
      $idempotenceKey
  );
?>

from yandex_checkout import Refund

payment = Refund.create({
  "amount": {
    "value": "2.00",
    "currency": "RUB"
  },
  "payment_id": "215d8da0-000f-50be-b000-0003308c89be"
})

Создает объект возврата — Refund. Возвращает успешно завершенный платеж по уникальному идентификатору этого платежа. Создание возврата возможно только для платежей в статусе succeeded. Комиссии за проведение возврата нет. Комиссия, которую Яндекс.Касса берёт за проведение исходного платежа, не возвращается.

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

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

{
  "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"
}

Параметры запроса
payment_id
string
required
Идентификатор платежа.
amount
object
Сумма, которую нужно вернуть пользователю.
value
string
required
Сумма в выбранной валюте. Выражается в виде строки и пишется через точку, например 10.00. Количество знаков после точки зависит от выбранной валюты.
currency
string
required
Код валюты в формате ISO-4217. Должен соответствовать валюте субаккаунта (recipient.gateway_id), если вы разделяете потоки платежей, и валюте аккаунта (shopId в личном кабинете), если не разделяете.
description
string
Комментарий к возврату, основание для возврата денег пользователю.
receipt
object
Данные для формирования чека в онлайн-кассе (для соблюдения 54-ФЗ). Необходимо указать что-то одно — телефон пользователя (phone) или его электронную почту (email).
items
array
required
Список товаров в заказе.
description
string
required
Название товара.
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
Признак предмета расчета. Перечень возможных значений
payment_mode
string
Признак способа расчета. Перечень возможных значений
tax_system_code
number
Система налогообложения магазина. Параметр необходим, только если у вас несколько систем налогообложения. В остальных случаях не передается. Подробнее про коды налогообложения.
phone
string
Телефон пользователя для отправки чека. Указывается в формате ITU-T E.164, например 79000000000.
email
string
Электронная почта пользователя для отправки чека.

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

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

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

<?php
  $refundId = '7894e5e2-a22e-434b-b6c1-e355ff096d1c';
  $refund = $client->getRefundInfo($refundId);
?>

from yandex_checkout import Refund

refund_id = '7894e5e2-a22e-434b-b6c1-e355ff096d1c'
payment = Refund.find_one(refund_id)

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

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

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

{
  "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"
}