Obtaining an OAuth token — Payment acceptance via the YooMoney API

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.

Step	Actions
Step 1. Request rights	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.
Step 2. Receive the verification code	Callback URL: User gives your app access. OAuth server adds the verification code or error code to the Callback URL which you entered when registering the app. OAuth server redirects the user to the Callback URL. You extract the verification code from the Callback URL. Code entered manually: User gives your app access. OAuth server displays the verification code on its page. User enters the code in your app.
Step3. Exchange the verification code for an OAuth token	The procedure is the same regardless of how you chose to receive the code: You send a POST request with the verification code to the OAuth server. OAuth server exchanges the code for a token and returns the token to you in the response body. The verification code must be exchanged for a token within 5 minutes.

Step

Actions

Step 1. Request rights

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.

Step 2. Receive the verification code

Callback URL:

User gives your app access.
OAuth server adds the verification code or error code to the Callback URL which you entered when registering the app.
OAuth server redirects the user to the Callback URL.
You extract the verification code from the Callback URL.

Code entered manually:

User gives your app access.
OAuth server displays the verification code on its page.
User enters the code in your app.

Step3. Exchange the verification code for an OAuth token

The procedure is the same regardless of how you chose to receive the code:

You send a POST request with the verification code to the OAuth server.
OAuth server exchanges the code for a token and returns the token to you in the response body.

The verification code must be exchanged for a token within 5 minutes.

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

Parameter	Description
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.

Rights can only be granted by the YooMoney user whose role is the Owner or Manager.

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

Parameter	Description
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

Parameter	Type	Description
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

Parameter	Type	Description
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.

A YooMoney OAuth token allows making financial transactions on behalf of the user. Only your app must have access to the token, so don't disclose it publicly or save it in your browser cookie files.

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

Parameter	Type	Description
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.