Чтобы пользователь мог использовать в вашем приложении возможности ЮKassa, вам нужно запросить у него разрешение и получить OAuth-токен.
Чтобы реализовать OAuth-авторизацию, вам понадобятся идентификатор приложения (Client ID) и пароль (Client Secret), которые вы получите после регистрации приложения на OAuth-сервере ЮKassa. Эти данные доступны в свойствах приложения (нажмите название приложения, чтобы открыть его свойства).
Чтобы получить токен, вам нужно запросить права, получить код подтверждения и обменять код на токен. Порядок действий зависит от выбранного способа получения кода подтверждения.
Шаг | Действия |
---|---|
Callback URL: Вы направляете пользователя на страницу OAuth-сервера ЮKassa для выдачи прав. Ручной ввод кода: Вы отображаете пользователю страницу OAuth-сервера ЮKassa для выдачи прав. Если на вашем устройстве недоступен браузер, вы отображаете QR-код или адрес. | |
Callback URL:
Ручной ввод кода:
| |
Порядок действий одинаковый для всех способов получения кода подтверждения:
|
Чтобы получить код подтверждения для 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 и подтвердит действие паролем из смс. Он может выбрать только один магазин. Если вам нужно получить доступ к нескольким магазинам пользователя, заново запросите права для каждого магазина.
Порядок действий зависит от способа получения кода, который вы выбрали при регистрации приложения.
После того, как пользователь выдаст права вашему приложению, 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-токен выдать не удалось, в ответе вернется ошибка.
Пример тела ответа с ошибкой
{ "error": "invalid_request", "error_description": "Auth code is not correct" }
Описание параметров при ответе об ошибке
Параметр | Тип | Описание |
---|---|---|
error | string | Код ошибки. Возможные значения:
Обязательный параметр |
error_description | string | Описание ошибки Необязательный параметр. |
Готово! Теперь токен можно использовать для взаимодействия с API ЮKassa.
Тестирование работы с OAuth-токенамиОтзыв OAuth-токена