OAuth authorization in Yandex.Checkout
If you want a user to work with Yandex.Checkout payments in your app, you need to get permission for carrying out transactions on their behalf: OAuth token. Implement authorization by the OAuth 2.0 protocol.
Procedure for OAuth authorization in Yandex.Checkout:
  1. Redirect the user to Yandex’s OAuth server and get an authorization code.
  2. Exchange the authorization code to an OAuth token.
  3. Use this token to interact with the Yandex.Checkout API.
Only Yandex.Checkout users with the Owner role can grant rights.
Below, we’ll describe the process of integration with Yandex.OAuth for interacting with the Yandex.Checkout API.
 Preparation
Before starting the process, you need to connect to the Yandex.Checkout partnership program and register your app in the Yandex.OAuth service.
 1. Become a Yandex.Checkout partner
Join the Yandex.Checkout partnership program: invite new users to Yandex.Checkout and get a percentage of their turnover.
Send a request for registration to agents@yamoney.ru to join the partnership program. In the request, tell us about your company and which Yandex.Checkout features you want to use. The Yandex.Checkout manager will contact you with the further instructions.
Registration requires a Yandex login.
 2. Register the app in Yandex.OAuth
Register your app with Yandex.OAuth. You will need to sign in to your Yandex account used for registration in the partnership program.
Select the set of rights for interacting with Yandex.Checkout in the Permissions section during the registration. You can request the following rights:
  • payment creation;
  • payment capture;
  • payment cancellation.
These rights are enough for proper payment acceptance via Yandex.Checkout.
The set of rights for interacting with Yandex.Checkout is available only to those who’ve joined the partnership program.
To implement OAuth authorization, you will need the app’s ID, password, and Callback URL that you’ll receive after registering the app in Yandex.OAuth. This information is available in the app’s properties (click on the app’s title to view its properties).
Properties of the created app
 Step 1. Get an authorization code
To get an authorization code for the Yandex.Checkout’s OAuth token, redirect the user to Yandex’s OAuth server.
Format of the URL for redirecting the user
https://oauth.yandex.com/authorize?response_type=code&client_id=<App ID>&device_id=<Device ID>&state=<value of the state parameter in request>
Description of parameters
ParameterDescription
response_typeRequired response. For Yandex.Checkout, specify the 
code
(authorization code) value.
Required parameter.
client_idYour app’s ID.
Required parameter.
device_idUnique ID of the device used for requesting the token.
To ensure the uniqueness, generate UUID once and use it for every new token request made from this device. You can also use the unique ID of the user’s account in your app as 
device_id
. The must be longer than 6 characters and shorter than 50. You can only use printable ASCII characters (with codes from 32 to 126).
If 
device_id
is not specified, and the user is trying to grant the rights to your app from the same device, you will receive an existing OAuth token.
This parameter is recommended for integration with the Yandex.Checkout.
stateThe state string, which Yandex.OAuth 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.
This parameter is recommended for integration with the Yandex.Checkout.
These are the parameters required for integration with Yandex.Checkout. You can view all of these parameters in the Yandex.OAuth documentation.
When the user grants the rights, they select one of their stores in Yandex.Checkout and confirm this action with a text message password. During this process they can select only one store. If you need access to several of the user’s stores, request the rights again with a unique
device_id
for each store.
After the user grants the rights to your app, Yandex’s OAuth server will redirect them to the Сallback URL you specified during app registration.
The code is valid for 10 minutes. You must exchange it to an OAuth token within this period, otherwise you will have to request it again.
Example of the URL the user will be redirected to in case of success
http://www.example.com/token?code=<confirmation code>&state=<value of the state parameter in request>
Description of parameters
ParameterDescription
codeThe authorization code that can be exchanged for an OAuth token.
Required parameter.
stateThe state string, which Yandex.OAuth 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.
More about error processing
Example of the URL the user will be redirected to in case of an error
http://www.example.com/token?error=<error code>&error_description=<error description>&state=<value of the state parameter in request>
 Step 2. Exchange the authorization code for an OAuth token
To exchange the authorization code to an OAuth token, send a POST request to the Yandex’s OAuth server and specify the authorization code, your ID, and the password.
Example of request
cURL
curl https://oauth.yandex.com/token \
  -u <App ID>:<App password> \
  -d grant_type=authorization_code \
  -d code=<Authorization code>
In response, the Yandex’s OAuth server will return the OAuth token in the 
access_token
field.
Example of response body with the OAuth token
JSON
{
  "token_type": "bearer",
  "access_token": "AQAAAACy1C6ZAAAAfa6vDLuItEy8pg-iIpnDxIs",
  "expires_in": 124234123534,
  "refresh_token": "1:GN686QVt0mmakDd9:A4pYuW9LGk0_UnlrMIWklkAuJkUWbq27loFekJVmSYrdfzdePBy7:A-2dHOmBxiXgajnD-kYOwQ"
}
Save an OAuth token for further interaction with the Yandex.Checkout API.
Yandex.Checkout’s OAuth token allows performing transactions on behalf of the user. The token must only be accessible to your app, so don’t publish it in open sources and don’t save it in the browser’s cookies.
If the OAuth token couldn’t be provided, the response will contain the error description.
The Yandex.Checkout’s OAuth tokens are renewable, meaning that the token expires after a few months, but the expiration date gets renewed after every authorization. You can see the minimum lifespan of a token during app registration. If an OAuth token has expired, Yandex.Checkout will return an error.
 Step 3. Use the OAuth token to interact with the Yandex.Checkout API
Use the received OAuth token for every request to the Yandex.Checkout API. Specify the OAuth token in the authorization header.
The only requests you can send to the Yandex.Checkout API are the ones you requested the rights for during app registration.
Example of request to the Yandex.Checkout API with an OAuth token
cURL
PHP
Python
curl https://payment.yandex.net/api/v3/me \
  -H 'Authorization: Bearer <OAuth token>' \
Example of the response body
JSON
{
  "account_id": "123",
  "test": false,
  "fiscalization_enabled": true
}
 See also
Yandex.OAuth documentationQuick startNotifications