Формат взаимодействия с API ЮKassa
Особенности
ЮKassa — универсальное решение для работы с онлайн-платежами и выплатами. API ЮKassa построено на REST-принципах, работает с реальными объектами и обладает предсказуемым поведением. С помощью этого API вы можете отправлять запросы на оплату, сохранять платежную информацию для повторных списаний, совершать возвраты, делать выплаты и многое другое.
API в качестве основного протокола использует HTTP, а значит подходит для разработки на любом языке программирования, который умеет работать с HTTP-библиотеками (cURL и другими).
API endpoint:
https://api.yookassa.ru/v3/API поддерживает POST, GET и DELETE-запросы. POST-запросы используют JSON-аргументы, GET и DELETE-запросы работают со строками запросов. API всегда возвращает ответ в формате JSON, независимо от типа запроса.
Аутентификация
Данные для аутентификации запросов необходимо передавать в заголовке запроса в параметре
Authorization.В ЮKassa есть два способа аутентификации запросов: HTTP Basic Auth (основной) и OAuth (только для тех, кто использует API для партнеров).
HTTP Basic Auth
Для аутентификации запросов необходимо использовать HTTP Basic Auth. В заголовках запросов в качестве имени пользователя необходимо передать идентификатор вашего магазина или шлюза в ЮKassa, в качестве пароля — ваш секретный ключ.
Секретный ключ отвечает за безопасность ваших данных. Храните его в защищенном месте и не публикуйте на сторонних ресурсах (например, вместе с примерами кода).
Пример запроса с аутентификацией
cURL
PHP
Python
from yookassa import Configuration Configuration.account_id = <Идентификатор магазина> Configuration.secret_key = <Секретный ключ>
Узнать идентификатор и выпустить секретный ключ (а также перевыпустить и удалить неактуальный) можно в личном кабинете ЮKassa. Если у вас нет доступа к личному кабинету, попросите владельца магазина добавить вас как пользователя с ролью Разработчик. Как добавить пользователя личного кабинета ЮKassa
Для тех, кто принимает платежи
Тем, кто принимает платежи, в том числе использует Сплитование платежей или Безопасную сделку, в запросах необходимо передавать идентификатор и секретный ключ магазина:
- Идентификатор указан в разделе Настройки — Магазин (поле shopId).
- Секретный ключ можно получить в разделе Интеграция — Ключи API. Ключ для настоящего магазина нужно сгенерировать и активировать паролем из смс, после чего скачать себе и сохранить в надежном месте. Для тестового магазина (или интернет‑площадки) секретный ключ выпускается автоматически и всегда доступен в личном кабинете. Подробнее о том, как выпустить, перевыпустить и удалить секретный ключ
Для тех, кто делает выплаты
Тем, кто проводит выплаты, в запросах необходимо передавать идентификатор и секретный ключ шлюза:
- Идентификатор указан в разделе Настройки выплат (поле agentId).
- Секретный ключ можно получить в разделе Интеграция — Ключи API. Ключ для настоящего шлюза нужно сгенерировать и активировать паролем из смс, после чего скачать себе и сохранить в надежном месте. Для тестового шлюза секретный ключ выпускается автоматически и всегда доступен в личном кабинете. Подробнее о том, как выпустить, перевыпустить и удалить секретный ключ
OAuth
Только для тех, кто использует API для партнеров
Если вы участвуете в партнерской программе ЮKassa, для аутентификации и авторизации запросов необходимо использовать OAuth 2.0.
Вам необходимо получить OAuth-токен и передавать его с каждым запросом.
Пример запроса с использованием OAuth-токена
cURL
PHP
Python
from yookassa import Configuration Configuration.configure_auth_token('<Bearer Token>')
OAuth-токен ЮKassa дает право выполнять финансовые операции от имени пользователя. Токен должен быть доступен только вашему приложению, поэтому не публикуйте его в открытых источниках и не сохраняйте в cookie браузера.
Идемпотентность
В контексте API идемпотентность означает, что многократные запросы обрабатываются так же, как однократные. Это значит, что, получив повторный запрос с теми же параметрами, ЮKassa выдаст в ответе результат исходного запроса. Такое поведение помогает избежать нежелательного повторения транзакций. Например, если при проведении платежа возникли проблемы с сетью, и соединение прервалось, вы сможете безопасно повторить нужный запрос неограниченное количество раз.
Для обеспечения идемпотентности используется заголовок
Idempotence-Key (или ключ идемпотентности). В заголовке Idempotence-Key можно передавать любое значение, уникальное для этой операции на вашей стороне. Длина не больше 64 символов. Рекомендуется использовать V4 UUID.Пример запроса с ключом идемпотентности
cURL
PHP
Python
from yookassa 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)
Если вы повторяете запрос с теми же данными и тем же ключом, API обрабатывает его как повторный. Если данные в запросе те же, а ключ идемпотентности отличается, запрос выполняется как новый.
Ключ идемпотентности нужно передавать для POST и DELETE-запросов. GET-запросы являются по умолчанию идемпотентными, так как не имеют нежелательных последствий.
ЮKassa обеспечивает идемпотентность в течение 24 часов после первого запроса, потом повторный запрос будет обработан как новый.
Обработка запросов
ЮKassa обрабатывает полученный запрос немедленно и возвращает результат обработки («успех» или «неудача»). Ответ содержит код ответа HTTP, стандартные заголовки и при необходимости тело ответа в формате JSON. Подробнее о формате ответа
Если в течение 30 секунд невозможно дать точный ответ, например из-за неполадок на стороне эквайера, ЮKassa вернет код ответа HTTP 500, а для запросов, связанных с платежами , также попытается отменить операцию.
HTTP 500 не говорит об успешности или неуспешности выполнения вашей операции. Поэтому при получении HTTP 500 вам необходимо сначала узнать результат обработки запроса и только после этого принимать любые решения, связанные с этой операцией.
Статья была полезна?
Да
Нет
Что почитать еще