YooMoney API
Guides
Old versions of the API
Help
Sign up for YooMoney
Receiving an OAuth token
To make YooMoney's features available to the user in your app, you need to request their permission and receive an OAuth token.
To implement OAuth, you'll need app's identifier (Client ID) and password (Client Secret) which you'll get after you register the app on YooMoney's OAuth server. This information is available in app's properties (click on app's name to open its properties).
 
Overview
To receive a token, you need to request rights, receive a verification code, and exchange the code for a token. The procedure depends on how you selected to receive the verification code.
StepActions
Callback URL: You redirect the user to the page of YooMoney's OAuth server for granting rights.
Code entered manually: you display the page of YooMoney's OAuth server for granting rights to the user. If the browser isn't available on your device, you'll display a QR code or address.
Callback URL:
  1. User gives your app access.
  2. OAuth server adds the verification code or error code to the Callback URL which you entered when registering the app.
  3. OAuth server redirects the user to the Callback URL.
  4. You extract the verification code from the Callback URL.
Code entered manually:
  1. User gives your app access.
  2. OAuth server displays the verification code on its page.
  3. User enters the code in your app.
The procedure is the same regardless of how you chose to receive the code:
  1. You send a POST request with the verification code to the OAuth server.
  2. OAuth server exchanges the code for a token and returns the token to you in the response body.
Step 1. Get an authorization code
To get an authorization code for the OAuth token, redirect the user to YooMoney’s OAuth server.
Format of the URL for redirecting the user
https://yookassa.ru/oauth/v2/authorize?client_id=<App ID>&response_type=<Required response>&state=<Value of the state parameter in request>
Description of parameters
ParameterDescription
response_type
Required response. Specify the code (authorization code) value.
Required parameter.
client_id
Your app’s ID.
Required parameter.
state
The state string, which YooMoney returns without making any changes. You can use it to identify the user you’re requesting the token from. Maximum allowed line length is 1024 characters.
Optional parameter.
Example of the URL the user will be redirected to in case of success
https://yookassa.ru/oauth/v2/authorize?client_id=tr2fhrsh0e7naugqmoq6tesc5h0sbpsv&response_type=code&state=324234
When granting rights, the user will select one of their stores in YooMoney and confirm the action with a text message code. They can only select one store. If you'd like to get access to multiple stores of the user, request the rights for each store again.
Step 2. Receive the verification code
The procedure depends on how you chose to receive the code when registering the app.
Receiving the code from Callback URL
After the user grants the rights to your app, the OAuth server will redirect them to the Callback URL that you entered when registering the app.
Example of the URL the user will be redirected to in case of success
http://www.example.com/app?code=rvunUlge6gUMx6TT0UT6ys4y398qqG73KQb1PjXETuX6eiQYJXXi-IrNHe49a9mt&state=324234
Description of parameters
ParameterDescription
code
The authorization code that can be exchanged for an OAuth token.
Required parameter.
state
The state string, which YooMoney returns without making any changes.
Optional parameter.
If the user refused to grant the rights, they will be returned to Callback URL with the access_denied error, and state.
Example of the URL the user will be redirected to in case of an error
http://www.example.com/token?error=access_denied&state=324234
Code entered manually by the user
After the user grants the rights to your app, the OAuth server will redirect them to the page where the verification code will be displayed. The user will need to enter this code on your app's page.
Step 3. Use the OAuth token to interact with the YooMoney API
You must exchange the verification code for a token within 5 minutes, otherwise you'll need to request a new code.
To exchange the verification code for an OAuth token, send a POST request to YooMoney's OAuth server and specify the code you received as well as your ID and password in it.
There are two ways to provide app's ID and password: in the body of the request or in the Authorization header by encoding the <App ID>:<App password> line using the base64 method and specifying the Basic authorization method. If you specify the Authorization header, the OAuth server will ignore the ID and password in the body of the request.
Example of request
cURL
curl https://yookassa.ru/oauth/v2/token \
  -u <App ID>:<App password> \
  -d grant_type=authorization_code \
  -d code=<Authorization code>
Description of parameters
ParameterTypeDescription
grant_type
string
Method of requesting an OAuth token. Fixed value: authorization_code (verification code).
Required parameter
code
string
Verification code received from YooMoney's OAuth server. Format: 7 to 256 characters. The validity period of a verification code is 5 minutes. If it has expired, request a new code.
Required parameter
client_id
string
App's ID (Client ID).
Required parameter if the Authorization header isn't specified. If the header is specified, this parameter is ignored.
client_secret
string
App's ID (Client ID).
Required parameter if the password is specified in the app settings and the Authorization header isn't specified in the request. If the header is specified, this parameter is ignored.
Example of request
cURL
curl https://yookassa.ru/oauth/v2/token \
  -u tr2fhrsh0e7naugqmoq6tesc5h0sbpsv:B2WKQeWPPm-zAtYTIflnO8udHwyeX_aQ5IgidAxW0lOehArrKf4J5FDb61CWcEim \
  -d grant_type=authorization_code \
  -d code=rvunUlge6gUMx6TT0UT6ys4y398qqG73KQb1PjXETuX6eiQYJXXi-IrNHe49a9mt \
The OAuth server will return an OAuth token in the access_token in response.
Example of response with an OAuth token
JSON
{
  "access_token": "AAEAAAAA8cSwPQAAAXUcZAXZ9hmYP3bKvY2r3ALwPYRYhrnOiKDEou9aLKiLYArHj2Tke-syRshb-1TQ1Ns_nQbc",   
  "expires_in": 94607999
}
Description of parameters after you successfully receive an OAuth token
ParameterTypeDescription
access_token
string
OAuth token with requested rights. Format: 32 to 512 characters.
Required parameter.
expires_in
string
Token's validity period in seconds.
Required parameter.
Use the received OAuth token for every request to the YooMoney API.
If the token isn't revoked successfully, error's description will be returned.
Example of the response body with an error
JSON
{
    "error": "invalid_request",
    "error_description": "Auth code is not correct"
}
Parameter descriptions for the error message
ParameterTypeDescription
error
string
Error code. Possible values:
  • invalid_client — invalid ID or password of the app;
  • invalid_grant — invalid or expired verification code;
  • invalid_request — invalid request format (one of the parameters isn't specified, specified twice, or specified outside of request's body);
  • invalid_scope — app's rights have changed after the verification code was generated;
  • server_error — technical difficulties on YooMoney's side, it's unknown if the request has been processed successfully, repeat the request later;
  • temporarily_unavailable — server temporarily unavailable, repeat the request later;
  • unsupported_grant_type — unsupported value of the grant_type parameter.
Required parameter
error_description
string
Error description
Optional parameter.
Done! Now the token can be used for interaction with the YooMoney API.
See also