Authorization request

The application uses the OS browser to send an Authorization Request to the YooMoney server.

To request a token, we recommend using the POST method (the equivalent of HTML “form submit”), and UTF‑8 encoding.

Request

Request format

POST /oauth/authorize HTTP/1.1
Host: yoomoney.ru
Content-Type: application/x-www-form-urlencoded
Content-Length: <content-length>

client_id=<client_id>&response_type=code
&redirect_uri=<redirect_uri>&scope=<scope>&instance_name=<instance_name>

Request parameters

Parameter	Type	Description
client_id	string	The client_id that was assigned to the application during registration.
response_type	string	Constant value: `code`.
redirect_uri	string	URI that the OAuth server sends the authorization result to. Must have a string value that exactly matches the `redirect_uri` parameter specified in the application registration data. Any additional parameters required for the application can be added at the end of the string.
scope	string	A list of requested permissions. Items in the list are separated by a space. List items are case-sensitive.
instance_name	string	Identifier of the authorization instance in the application. Optional parameter. It allows you to get multiple authorizations for a single application.

Example of request parameters

client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ01
response_type=code
redirect_uri=https://client.example.com/cb
scope=account-info operation-history

Request example

POST /oauth/authorize HTTP/1.1
Host: yoomoney.ru
Content-Type: application/x-www-form-urlencoded
Content-Length: 191

client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ01&response_type=code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&scope=account%2Dinfo%20operation%2Dhistory

It is forbidden to send a request (open a page) directly from the application, since the payment service regulations require that a user’s login name, password, and payment password may be entered only on pages of the YooMoney service.

For the authorization request, the user is redirected to the YooMoney authorization page. The user enters his login and password, reviews the list of requested permissions and payment limits, and either approves or rejects the application’s authorization request.

Response

The authorization result is returned as an HTTP 302 Redirect. The application must process the HTTP Redirect response.

An individual application can only get one authorization per user.Repeated authorizations (with the same value for the client_id parameter) annul the permissions previously granted.

There is a way to get multiple authorizations for a single user: to do this, specify the instance_name parameter. In this case, repeated authorization considers both parameters, client_id and instance_name.

For the instance_name value, we recommend using a unique identifier of the user within the application, such as the user’s login name.

HTTP Redirect callback parameters

Parameter	Type	Description
code	string	Temporary token (authorization code); should be exchanged immediately for a permanent access token. Present if the user confirmed authorization of the application.
error	string	Error code. Present if an error occurred or authorization was declined by the user.
error_description	string	Additional text explanation of the error.

Possible errors (value of the error field)

Error code	Description	Behavior of the service
invalid_request	The request is missing required parameters, or parameters have unsupported or invalid values.	Page with the error message text.
invalid_scope	The scope parameter is missing, or it has an invalid value or a contradiction in logic.	Page with the error message text.
unauthorized_client	The `client_id` value is invalid, or the application does not have rights to request authorization (for example, its `client_id` has been blocked by YooMoney).	Page with the error message text.
access_denied	Authorization request was declined by the user.	Redirect to the application with the error code.

Example of the YooMoney response for successful authorization

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=i1WsRn1uB1ehfbb37

Response from YooMoney when authorization is declined

HTTP/1.1 302 Found
Location: https://client.example.com/cb?error=access_denied

The temporary authorization code (the value from the code field in the response) must be immediately exchanged for an access token. This token is valid for less than one minute.

The application must be able to receive and process the response from the YooMoney server and immediately exchange the temporary authorization code for the access token.

If the application was not able to get a response from the server, or the temporary authorization code was lost or expired, the authorization process must be repeated.