Receiving a token

If authorization was completed successfully, the application should immediately exchange the temporary authorization code for an access token. To do this, a request containing the temporary authorization code must be sent to the YooMoney OAuth server.

Request

The request must be sent using the POST method.

Request format

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

code=<code>&client_id=<client_id>&grant_type=authorization_code&redirect_uri=<redirect_uri>

Request parameters

Parameter	Type	Description
code	string	Temporary token (`authorization code`).
client_id	string	The `client_id` that was assigned to the application during registration.
grant_type	string	Constant value: `authorization_code`.
redirect_uri	string	URI that the OAuth server sends the authorization result to. The value of this parameter must exactly match the `redirect_uri` value from the previous `authorize` call.
client_secret	string	A secret word for verifying the application’s authenticity. Specified if the service is registered with the option to verify authenticity.

Request example without verifying authenticity

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

code=0DF3343A8D9C7B005B1952D9B933DC56ACB7FED6D3F2590A6FD90EC6391050EDFFCC993D325B41B00F58E5383F37F6831E8F415696E1CF07676EE8D0A3655CDD7C667189DFB69BFDB7116C0329303AB2554290048BAF9B767B4C335BF0E85830AC017AD2F14D97F529893C202D3B2C27A61EE53DC4FB04DAE8E815DE2E3F865F&client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ01&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

Request example with authenticity verification using a secret word

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

code=0DF3343A8D9C7B005B1952D9B933DC56ACB7FED6D3F2590A6FD90EC6391050EDFFCC993D325B41B00F58E5383F37F6831E8F415696E1CF07676EE8D0A3655CDD7C667189DFB69BFDB7116C0329303AB2554290048BAF9B767B4C335BF0E85830AC017AD2F14D97F529893C202D3B2C27A61EE53DC4FB04DAE8E815DE2E3F865F&client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ01&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&client_secret=NH2FGEYIS57DXVO4CJ4APTQVWWH78JZ140EIMJ5YOLTG0TQV0OIM9WBN1DGRZ3LP9AJK8ROAGMZFELPNK863HPRCF14CLWQXX66DSBHT3Z1X9WDC2I7MNKEWFY9285ARSW57QSWKBYB0263V

Response

In response to the request, the YooMoney server returns access_token, which is a symmetric key for the application that authorizes operations using the user account.

The token is returned in the format of a JSON document, which can contain one of the following fields (depending on the results):

Parameter	Type	Description
access_token	string	Access token. Present if successful.
error	string	Error code. Present if an error occurred.

Possible errors (value of the error field)

Error code	Description
invalid_request	The request is missing required parameters, or parameters have unsupported or invalid values.
unauthorized_client	The `client_id` or `client_secret` value is invalid, or the application does not have rights to request authorization (for example, its `client_id` has been blocked by YooMoney).
invalid_grant	The `access_token` could not be issued. Either the temporary authorization code was not issued by YooMoney, or it has expired, or an `access_token` has already been issued for this temporary authorization code (a duplicate request for an access token using the same temporary authorization code).

Example response for successfully exchanging the temporary authorization code

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 293
Cache-Control: no-store

{
  "access_token":"410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123"
}

Example of error response

HTTP/1.1 400 Bad Request
Content-Type: application/json
Content-Length: 25
Cache-Control: no-store

{
  "error":"invalid_grant"
}

The temporary authorization code can only be used once. If the application was not able to get a response from the server before the temporary authorization code expired, the entire authorization process must be repeated.

The access_token is a symmetric authorization key, so the application developer must secure it - the token should be encrypted for storage, with access allowed only after the user authenticates within the application. For example, the token can be encrypted using the 3DES algorithm, where the encryption key is a 4-digit PIN code.

Tokens received before 7 February 2018 are valid for 6 months. Tokens received after are valid for 3 years.