Основы
Формат взаимодействия
Яндекс.Касса — универсальное решение для работы с онлайн-платежами. API Яндекс.Кассы построено на REST-принципах, работает с реальными объектами и обладает предсказуемым поведением. С помощью этого API вы можете отправлять запросы на оплату, сохранять платежную информацию для повторных списаний, совершать возвраты и многое другое.
API в качестве основного протокола использует HTTP, а значит, подходит для разработки на любом языке программирования, который умеет работать с HTTP-библиотеками (cURL и другими).
API поддерживает POST и GET-запросы. POST-запросы используют JSON-аргументы, GET-запросы работают со строками запросов. API всегда возвращает ответ в формате JSON, независимо от типа запроса.
Аутентификация
Для аутентификации запросов используется HTTP Basic Auth. В заголовках запросов в качестве имени пользователя необходимо передать идентификатор вашего магазина в Яндекс.Кассе, в качестве пароля — ваш секретный ключ (его нужно сгенерировать и активировать паролем из смс).
Пример запроса с аутентификацией
cURL
PHP
Python
curl https://payment.yandex.net/api/v3/payments/{payment_id} \
  -u <Идентификатор магазина>:<Секретный ключ>
Узнать идентификатор и выпустить секретный ключ (а также перевыпустить и удалить неактуальный) можно в личном кабинете Яндекс.Кассы, в разделе Настройки.
Секретный ключ отвечает за безопасность ваших данных. Храните его в защищенном месте и не публикуйте на сторонних ресурсах (например, вместе с примерами кода).
Идемпотентность
В контексте API идемпотентность означает, что многократные запросы обрабатываются так же, как однократные.
Это значит, что получив повторный запрос с теми же параметрами, Яндекс.Касса выдаст в ответе результат исходного запроса.
Такое поведение помогает избежать нежелательного повторения транзакций. Например, если при проведении платежа возникли проблемы с сетью, и соединение прервалось, вы сможете безопасно повторить нужный запрос неограниченное количество раз.
GET-запросы являются по умолчанию идемпотентными, так как не имеют нежелательных последствий.
Для обеспечения идемпотентности POST-запросов используется заголовок
Idempotence-Key
(или ключ идемпотентности).
Пример запроса с ключом идемпотентности
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"
      }'
Если вы повторяете запрос с теми же данными и тем же ключом, API обрабатывает его как повторный. Если данные в запросе те же, а ключ идемпотентности отличается, запрос выполняется как новый.
В заголовке
Idempotence-Key
можно передавать любое значение, уникальное для этой операции на вашей стороне. Мы рекомендуем использовать V4 UUID.
Яндекс.Касса обеспечивает идемпотентность в течение 24 часов после первого запроса, потом повторный запрос будет обработан как новый.
HTTP-коды ответов
Если в процессе обработки запроса произойдет ошибка, 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
Пример тела ответа ошибки
JSON
  {
    "type": "error",
    "id": "ab5a11cd-13cc-4e33-af8b-75a74e18dd09",
    "code": "invalid_request",
    "description": "Idempotence key duplicated",
    "parameter": "Idempotence-Key"
  }
Что почитать еще
Неуспешные платежиТестированиеВходящие уведомленияБыстрый старт