Чтобы пользователь мог использовать в вашем приложении возможности ЮKassa, вам нужно запросить у него разрешение и получить OAuth-токен.
Чтобы реализовать OAuth-авторизацию, вам понадобятся идентификатор приложения (Client ID) и пароль (Client Secret), которые вы получите после регистрации приложения на OAuth-сервере ЮKassa. Эти данные доступны в свойствах приложения (нажмите название приложения, чтобы открыть его свойства).
Чтобы получить токен, вам нужно запросить права, получить код подтверждения и обменять код на токен. Порядок действий зависит от выбранного способа получения кода подтверждения.
Шаг | Действия |
---|---|
Callback URL: Вы направляете пользователя на страницу OAuth-сервера ЮKassa для выдачи прав. Ручной ввод кода: Вы отображаете пользователю страницу OAuth-сервера ЮKassa для выдачи прав. Если на вашем устройстве недоступен браузер, вы отображаете QR-код или адрес. | |
Callback URL:
Ручной ввод кода:
| |
Порядок действий одинаковый для всех способов получения кода подтверждения:
Код подтверждения нужно обменять на токен в течение 5 минут. |
Чтобы получить код подтверждения для OAuth-токена, перенаправьте пользователя на OAuth-сервер ЮKassa.
Формат адреса для перенаправления пользователя
https://yookassa.ru/oauth/v2/authorize?client_id=<Идентификатор приложения>&response_type=<Способ получения кода>&state=<Значение параметра state в запросе>
Описание параметров
Параметр | Описание |
---|---|
response_type | Способ получения токена. Фиксированное значение — code (код подтверждения).Обязательный параметр. |
client_id | Идентификатор вашего приложения. Обязательный параметр. |
state | Строка состояния, которую OAuth-сервер возвращает без изменения. Можно использовать для идентификации пользователя, для которого запрашивается токен. Максимальная допустимая длина строки — 1024 символа. Необязательный параметр. |
Пример адреса для перенаправления пользователя
https://yookassa.ru/oauth/v2/authorize?client_id=tr2fhrsh0e7naugqmoq6tesc5h0sbpsv&response_type=code&state=324234
Когда пользователь будет выдавать права, он выберет один из своих магазинов ЮKassa и подтвердит действие паролем из смс. Он может выбрать только один магазин. Если вам нужно получить доступ к нескольким магазинам пользователя, заново запросите права для каждого магазина.
Выдать права может только пользователь ЮKassa с ролью Владелец.
Порядок действий зависит от способа получения кода, который вы выбрали при регистрации приложения.
После того, как пользователь выдаст права вашему приложению, OAuth-сервер перенаправит его на Сallback URL, который вы указали при регистрации приложения.
Пример URL, на который будет перенаправлен пользователь в случае успеха
http://www.example.com/app?code=rvunUlge6gUMx6TT0UT6ys4y398qqG73KQb1PjXETuX6eiQYJXXi-IrNHe49a9mt&state=324234
Описание параметров
Параметр | Описание |
---|---|
code | Код подтверждения, который можно обменять на OAuth-токен. Обязательный параметр. |
state | Строка состояния, которую OAuth-сервер возвращает без изменения. Необязательный параметр. |
Если пользователь отказался давать разрешение, он вернется на Callback URL с ошибкой
access_denied
и state
, переданным в запросе.Пример URL, на который будет перенаправлен пользователь в случае неудачи
http://www.example.com/token?error=access_denied&state=324234
После того как пользователь выдаст права вашему приложению, OAuth-сервер ЮKassa перенаправит его на страницу, на которой будет показан код подтверждения. Пользователю нужно ввести этот код на странице вашего приложения.
Код подтверждения нужно обменять на токен в течение 5 минут, иначе код придется запрашивать заново.
Чтобы обменять код подтверждения на OAuth-токен, отправьте POST-запрос на OAuth-сервер ЮKassa и передайте в нём полученный код, свой идентификатор и пароль.
Идентификатор и пароль приложения можно передать двумя способами: в теле запроса или в заголовке Authorization, закодировав строку
<Идентификатор приложения>:<Пароль приложения>
методом base64 и указав базовый метод авторизации (Basic). Если передать заголовок Authorization, OAuth-сервер проигнорирует идентификатор и пароль в теле запроса.Формат запроса
curl https://yookassa.ru/oauth/v2/token \ -u <Идентификатор приложения>:<Пароль приложения> \ -d grant_type=authorization_code \ -d code=<Код подтверждения>
Описание параметров
Параметр | Тип | Описание |
---|---|---|
grant_type | string | Способ запроса OAuth-токена. Фиксированное значение: authorization_code — код подтверждения.Обязательный параметр |
code | string | Код подтверждения, полученный от OAuth-сервера ЮKassa. Формат — от 7 до 256 символов. Время жизни кода подтверждения — 5 минут. Если время вышло, запросите код заново. Обязательный параметр. |
client_id | string | Идентификатор приложения (Client ID). Обязательный параметр, если не передан заголовок Authorization. Если заголовок передан, параметр игнорируется. |
client_secret | string | Пароль приложения (Client Secret). Обязательный параметр, если пароль задан в настройках приложения и в запросе не передан заголовок Authorization. Если заголовок передан, параметр игнорируется. |
Пример запроса
curl https://yookassa.ru/oauth/v2/token \ -u tr2fhrsh0e7naugqmoq6tesc5h0sbpsv:B2WKQeWPPm-zAtYTIflnO8udHwyeX_aQ5IgidAxW0lOehArrKf4J5FDb61CWcEim \ -d grant_type=authorization_code \ -d code=rvunUlge6gUMx6TT0UT6ys4y398qqG73KQb1PjXETuX6eiQYJXXi-IrNHe49a9mt \
В ответ OAuth-сервер вернет OAuth-токен в поле
access_token
.Пример тела ответа с OAuth-токеном
{ "access_token": "AAEAAAAA8cSwPQAAAXUcZAXZ9hmYP3bKvY2r3ALwPYRYhrnOiKDEou9aLKiLYArHj2Tke-syRshb-1TQ1Ns_nQbc", "expires_in": 94607999 }
Описание параметров при успешном получении токена
Параметр | Тип | Описание |
---|---|---|
access_token | string | OAuth-токен с запрошенными правами. Формат: от 32 до 512 символов. Обязательный параметр |
expires_in | string | Время жизни токена в секундах. Обязательный параметр. |
Сохраните токен и используйте его для обращения в API ЮKassa.
OAuth-токен ЮKassa дает право выполнять финансовые операции от имени пользователя. Токен должен быть доступен только вашему приложению, поэтому не публикуйте его в открытых источниках и не сохраняйте в cookie браузера.
Если OAuth-токен выдать не удалось, в ответе вернется ошибка.
Пример тела ответа с ошибкой
{ "error": "invalid_request", "error_description": "Auth code is not correct" }
Описание параметров при ответе об ошибке
Параметр | Тип | Описание |
---|---|---|
error | string | Код ошибки. Возможные значения:
Обязательный параметр |
error_description | string | Описание ошибки Необязательный параметр. |
Готово! Теперь токен можно использовать для взаимодействия с API ЮKassa.
Есть вопросы или замечания по документации?
Можем созвониться и обсудить их лично: мы поможем вам разобраться, а вы нам — понять, что тут нужно улучшить.
Для этого оставьте свои контакты и выберите время.
Да, хочу обсудить