Accessing finance methods

You can manage access to finance methods and get a master token in the Yandex.Direct web interface.

To use the finance methods, you must first enable access to them and get a master token in the web interface. Finance tokens are generated based on the master token. A finance token must be specified for every call of a finance method.

Getting a master token

The master token is used for generating finance tokens, which are necessary for calling finance methods. To get a master token, you must log in to Yandex.Direct with the username that will be used for making finance method calls in the future.

  1. Go to the Financial transactions tab on the Direct API access management page.

  2. Select the Allow financial transactions option and click the Save changes button.
  3. Click the Issue new master token button.

    Attention.

    When the master token is received, the previous master token becomes invalid and can no longer be used.

    You will see a window for entering the payment password (this is required for confirmation of any actions in Yandex that involve finances). If a payment password has not been used yet, you will be able to create one.

  4. Type the payment password and click the Enter button.

    A new master token is displayed, as shown in the screenshot.

    Attention.

    The master token is displayed one time in the web interface. If you do not save it, you will not be able to retrieve it later, and you will need to get a new master token.

  5. Click the Back to settings link.

    The master token date of issue is displayed.

  6. To make the current master token invalid without generating a new token, click the Reset master token button.

    Resetting is equivalent to prohibiting financial transactions, since finance tokens can't be generated without an active master token.

  7. To have the Yandex.Direct API delete the number of the last financial transaction, click Reset counter.

    Resetting is useful if the application has lost track of financial transaction numbering. After the reset, numbering can start over.

Finance token

When calling a finance method, the following additional parameters must be specified:

  • operation_num — The sequential transaction number.
  • finance_token — The finance token.

See the JSON and SOAP examples.

The operation_num parameter — an integer in the range from 1 to 9223372036854775807. For each call of a finance method, the transaction number must be higher than in the previous call of any finance method. Any starting number and any increment can be used.

The finance_token parameter must be formed using SHA256 encoding. The string that is encrypted is a concatenation of the following substrings:

  • The master token.
  • The transaction number (operation_num parameter).
  • The name of the finance method being invoked.
  • The name of the operation (for the AccountManagement (Live) method).
  • The standardized username that the API request is on behalf of.

    Attention. If the username contains dots or uppercase characters (capital letters), the username should be standardized by replacing them with hyphens and lowercase characters, respectively.

Example of generating a finance token:

Python

import hashlib
masterToken  = 'AEgchkX2M3FBL8lU'
operationNum = 119
usedMethod   = 'CreateInvoice'
login        = 'agrom'
financeToken = hashlib.sha256(masterToken + str(operationNum) + usedMethod + login).hexdigest()
Attention. After ten consecutive finance method calls with an invalid transaction number or access token, access to finance methods is blocked. Access can be enabled again in the Yandex.Direct web interface by resetting the transactions counter.

PHP

$master_token = 'AEgchkX2M3FBL8lU';
$operation_num = 119;
$used_method = 'CreateInvoice';
$login = 'agrom';
$finance_token = hash("sha256", $master_token . $operation_num . $used_method . $login);
Attention. After ten consecutive finance method calls with an invalid transaction number or access token, access to finance methods is blocked. Access can be enabled again in the Yandex.Direct web interface by resetting the transactions counter.