Получение OAuth-токена — Прием платежей в пользу интернет-магазина по API ЮKassa

Получение OAuth-токена

Чтобы пользователь мог использовать в вашем приложении возможности ЮKassa, вам нужно запросить у него разрешение и получить OAuth-токен.

Чтобы реализовать OAuth-авторизацию, вам понадобятся идентификатор приложения (Client ID) и пароль (Client Secret), которые вы получите после регистрации приложения на OAuth-сервере ЮKassa. Эти данные доступны в свойствах приложения (нажмите название приложения, чтобы открыть его свойства).

Обзор

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

Шаг	Действия
Шаг 1. Запросите права	Callback URL: Вы направляете пользователя на страницу OAuth-сервера ЮKassa для выдачи прав. Ручной ввод кода: Вы отображаете пользователю страницу OAuth-сервера ЮKassa для выдачи прав. Если на вашем устройстве недоступен браузер, вы отображаете QR-код или адрес.
Шаг 2. Получите код подтверждения	Callback URL: Пользователь разрешает доступ вашему приложению. OAuth-сервер добавляет код подтверждения или код ошибки к Callback URL, который вы указали при регистрации приложения. OAuth-сервер перенаправляет пользователя на Callback URL. Вы извлекаете код подтверждения из Callback URL. Ручной ввод кода: Пользователь разрешает доступ вашему приложению. OAuth-сервер отображает на своей странице код подтверждения. Пользователь вводит код в вашем приложении.
Шаг 3. Обменяйте код подтверждения на OAuth-токен	Порядок действий одинаковый для всех способов получения кода подтверждения: Вы отправляете OAuth-серверу POST-запрос с кодом подтверждения. OAuth-сервер обменивает код на токен и возвращает вам токен в теле ответа. Код подтверждения нужно обменять на токен в течение 5 минут.

Шаг 1. Запросите у пользователя права

Чтобы получить код подтверждения для 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 с ролью Владелец.

Шаг 2. Получите код подтверждения

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

Получение кода из Callback URL

После того, как пользователь выдаст права вашему приложению, 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 перенаправит его на страницу, на которой будет показан код подтверждения. Пользователю нужно ввести этот код на странице вашего приложения.

Шаг 3. Обменяйте код подтверждения на OAuth-токен

Код подтверждения нужно обменять на токен в течение 5 минут, иначе код придется запрашивать заново.

Чтобы обменять код подтверждения на OAuth-токен, отправьте POST-запрос на OAuth-сервер ЮKassa и передайте в нём полученный код, свой идентификатор и пароль.

Идентификатор и пароль приложения можно передать двумя способами: в теле запроса или в заголовке Authorization, закодировав строку <Идентификатор приложения>:<Пароль приложения> методом base64 и указав базовый метод авторизации (Basic). Если передать заголовок Authorization, OAuth-сервер проигнорирует идентификатор и пароль в теле запроса.

Формат запроса

cURL
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
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-токеном

JSON
{
  "access_token": "AAEAAAAA8cSwPQAAAXUcZAXZ9hmYP3bKvY2r3ALwPYRYhrnOiKDEou9aLKiLYArHj2Tke-syRshb-1TQ1Ns_nQbc",   
  "expires_in": 94607999
}

Описание параметров при успешном получении токена

Параметр	Тип	Описание
access_token	string	OAuth-токен с запрошенными правами. Формат: от 32 до 512 символов. Обязательный параметр
expires_in	string	Время жизни токена в секундах. Обязательный параметр.

Сохраните токен и используйте его для обращения в API ЮKassa.

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

Если OAuth-токен выдать не удалось, в ответе вернется ошибка.

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

JSON
{
    "error": "invalid_request",
    "error_description": "Auth code is not correct"
}

Описание параметров при ответе об ошибке

Параметр	Тип	Описание
error	string	Код ошибки. Возможные значения: `invalid_client` — неверный идентификатор приложения или пароль; `invalid_grant` — неверный или просроченный код подтверждения; `invalid_request` — неверный формат запроса (один из параметров не указан, указан дважды, или передан не в теле запроса); `invalid_scope` — права приложения изменились после генерации кода подтверждения; `server_error` — технические неполадки на стороне ЮKassa, результат обработки запроса неизвестен, повторите запрос позже; `temporarily_unavailable` — сервер временно недоступен, повторите запрос позже; `unsupported_grant_type` — недопустимое значение параметра `grant_type`. Обязательный параметр
error_description	string	Описание ошибки Необязательный параметр.

Готово! Теперь токен можно использовать для взаимодействия с API ЮKassa.

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

Тестирование работы с OAuth-токенами Отзыв OAuth-токена