Основы работы с API — Прием оплаты по API ЮKassa

Основы работы с API

Формат взаимодействия

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

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

API endpoint:

https://api.yookassa.ru/v3/

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

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

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

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

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

Узнать идентификатор и выпустить секретный ключ (а также перевыпустить и удалить неактуальный) можно в личном кабинете ЮKassa, в разделе Интеграция — Ключи API.

Секретный ключ отвечает за безопасность ваших данных. Храните его в защищенном месте и не публикуйте на сторонних ресурсах (например, вместе с примерами кода).

Для партнеров

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

Вам необходимо получить OAuth-токен и передавать его с каждым запросом.

Пример запроса с использованием OAuth-токена

cURL
PHP
Python
curl https://api.yookassa.ru/v3/payments/{payment_id} \
  -H "Authorization: Bearer <OAuth-токен>"

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

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

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

Это значит, что получив повторный запрос с теми же параметрами, ЮKassa выдаст в ответе результат исходного запроса.

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

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

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

Idempotence-Key

(или ключ идемпотентности).

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

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

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

В заголовке

Idempotence-Key

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

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

Обработка запросов

ЮKassa обрабатывает полученный запрос немедленно и возвращает результат обработки («успех» или «неудача»).

Если в течение 30 секунд невозможно дать точный ответ, например из-за неполадок на стороне эквайера, ЮKassa вернет HTTP-код 500 и попытается отменить операцию.

Чтобы узнать окончательный результат обработки запроса, повторите запрос с теми же данными и с тем же ключом идемпотентности. Рекомендуемая частота повторений: один раз в минуту до тех пор, пока ЮKassa не сообщит ответ, отличный от HTTP 500.

HTTP-коды ответов

Если запрос обработан успешно, API вернет HTTP-код 200 и тело ответа.

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

HTTP-код	Код ошибки	Описание
400	invalid_request, not_supported	Неправильный запрос. Чаще всего этот статус выдается из-за нарушения правил взаимодействия с API.
401	invalid_credentials	[Basic Auth] Неверный идентификатор вашего аккаунта в ЮKassa или секретный ключ (имя пользователя и пароль при аутентификации). [OAuth 2.0] Невалидный OAuth-токен: он некорректный, устарел или его отозвали. Запросите токен заново.
403	forbidden	Секретный ключ или OAuth-токен верный, но не хватает прав для совершения операции.
404	not_found	Ресурс не найден.
429	too_many_requests	Превышен лимит запросов в единицу времени. Попробуйте снизить интенсивность запросов.
500	internal_server_error	Технические неполадки на стороне ЮKassa. Результат обработки запроса неизвестен. Повторите запрос позднее с тем же ключом идемпотентности. Рекомендуется повторять запрос с периодичностью один раз в минуту до тех пор, пока ЮKassa не сообщит результат обработки операции.

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

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

Есть вопросы или замечания по документации?

Можем созвониться и обсудить их лично: мы поможем вам разобраться, а вы нам — понять, что тут нужно улучшить. Для этого оставьте свои контакты и выберите время.

Да, хочу обсудить

Что почитать еще

Неуспешные платежи Тестирование Входящие уведомления Быстрый старт

Формат взаимодействия