Инструкции
Помощь
Подключить ЮKassa
Получение OAuth-токена
Чтобы пользователь мог использовать в вашем приложении возможности ЮKassa, вам нужно запросить у него разрешение и получить OAuth-токен.
Чтобы реализовать OAuth-авторизацию, вам понадобятся идентификатор приложения (Client ID) и пароль (Client Secret), которые вы получите после регистрации приложения на OAuth-сервере ЮKassa. Эти данные доступны в свойствах приложения (нажмите название приложения, чтобы открыть его свойства).
Обзор
Чтобы получить токен, вам нужно запросить права, получить код подтверждения и обменять код на токен. Порядок действий зависит от выбранного способа получения кода подтверждения.
ШагДействия
Callback URL: Вы направляете пользователя на страницу OAuth-сервера ЮKassa для выдачи прав.
Ручной ввод кода: Вы отображаете пользователю страницу OAuth-сервера ЮKassa для выдачи прав. Если на вашем устройстве недоступен браузер, вы отображаете QR-код или адрес.
Callback URL:
  1. Пользователь разрешает доступ вашему приложению.
  2. OAuth-сервер добавляет код подтверждения или код ошибки к Callback URL, который вы указали при регистрации приложения.
  3. OAuth-сервер перенаправляет пользователя на Callback URL.
  4. Вы извлекаете код подтверждения из Callback URL.
Ручной ввод кода:
  1. Пользователь разрешает доступ вашему приложению.
  2. OAuth-сервер отображает на своей странице код подтверждения.
  3. Пользователь вводит код в вашем приложении.
Порядок действий одинаковый для всех способов получения кода подтверждения:
  1. Вы отправляете OAuth-серверу POST-запрос с кодом подтверждения.
  2. OAuth-сервер обменивает код на токен и возвращает вам токен в теле ответа.
Шаг 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 и подтвердит действие паролем из смс. Он может выбрать только один магазин. Если вам нужно получить доступ к нескольким магазинам пользователя, заново запросите права для каждого магазина.
Шаг 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_typestring
Способ запроса OAuth-токена. Фиксированное значение: authorization_code — код подтверждения.
Обязательный параметр
codestring
Код подтверждения, полученный от OAuth-сервера ЮKassa. Формат — от 7 до 256 символов. Время жизни кода подтверждения — 5 минут. Если время вышло, запросите код заново.
Обязательный параметр.
client_idstring
Идентификатор приложения (Client ID).
Обязательный параметр, если не передан заголовок Authorization. Если заголовок передан, параметр игнорируется.
client_secretstring
Пароль приложения (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_tokenstring
OAuth-токен с запрошенными правами. Формат: от 32 до 512 символов.
Обязательный параметр
expires_instring
Время жизни токена в секундах.
Обязательный параметр.
Сохраните токен и используйте его для обращения в API ЮKassa.
Если OAuth-токен выдать не удалось, в ответе вернется ошибка.
Пример тела ответа с ошибкой
JSON
{
    "error": "invalid_request",
    "error_description": "Auth code is not correct"
}
Описание параметров при ответе об ошибке
ПараметрТипОписание
errorstring
Код ошибки. Возможные значения:
  • invalid_client — неверный идентификатор приложения или пароль;
  • invalid_grant — неверный или просроченный код подтверждения;
  • invalid_request — неверный формат запроса (один из параметров не указан, указан дважды, или передан не в теле запроса);
  • invalid_scope — права приложения изменились после генерации кода подтверждения;
  • server_error — технические неполадки на стороне ЮKassa, результат обработки запроса неизвестен, повторите запрос позже;
  • temporarily_unavailable — сервер временно недоступен, повторите запрос позже;
  • unsupported_grant_type — недопустимое значение параметра grant_type.
Обязательный параметр
error_descriptionstring
Описание ошибки
Необязательный параметр.
Готово! Теперь токен можно использовать для взаимодействия с API ЮKassa.
Что почитать еще
Тестирование работы с OAuth-токенамиОтзыв OAuth-токена