Yandex.Money API API for Apps 13.09.2018 - Yandex Technologies

 
Yandex.Money API
API for Apps

13.09.2018
Yandex.Money API. API for Apps. Version 1.8
Document build date: 13.09.2018.
This volume is a part of Yandex technical documentation.
Yandex helpdesk site: http://help.yandex.ru
© 2008—2018 Yandex LLC. All rights reserved.

Copyright Disclaimer
Yandex (and its applicable licensor) has exclusive rights for all results of intellectual activity and equated to them means of individualization, used for development, support,
and usage of the service Yandex.Money API. It may include, but not limited to, computer programs (software), databases, images, texts, other works and inventions, utility
models, trademarks, service marks, and commercial denominations. The copyright is protected under provision of Part 4 of the Russian Civil Code and international laws.
You may use Yandex.Money API or its components only within credentials granted by the Terms of Use of Yandex.Money API or within an appropriate Agreement.
Any infringements of exclusive rights of the copyright owner are punishable under civil, administrative or criminal Russian laws.

Contact information
Yandex LLC
http://www.yandex.com
Phone: +7 495 739 7000
Email: pr@yandex-team.ru
Headquarters: 16 L'va Tolstogo St., Moscow, Russia 119021
Contents
............................................................................................................................................................................................................... 4
Scenarios for receiving payments using Yandex.Checkout ................................................................................................................. 5
Application authorization flow ......................................................................................................................................................... 9
    Application authorization flow .................................................................................................................................................... 9
    App registration ......................................................................................................................................................................... 11
    Authorization Request ............................................................................................................................................................... 11
    Access token request .................................................................................................................................................................. 14
    Revoking a token ....................................................................................................................................................................... 16
    Access token scope .................................................................................................................................................................... 17
Protocol overview ............................................................................................................................................................................. 21
    Request format ........................................................................................................................................................................... 21
    Response format ......................................................................................................................................................................... 22
    Data types ................................................................................................................................................................................... 23
Information about a user's account ................................................................................................................................................ 25
    account-info method .................................................................................................................................................................. 25
     operation-history method ........................................................................................................................................................... 27
     operation-details method ............................................................................................................................................................ 31
Payments from the Yandex.Money wallet ..................................................................................................................................... 34
   Payments from the Yandex.Money wallet ................................................................................................................................. 34
   request-payment method ............................................................................................................................................................ 35
   process-payment method ........................................................................................................................................................... 42
   incoming-transfer-accept method .............................................................................................................................................. 48
   incoming-transfer-reject method ................................................................................................................................................ 49
Payments from bank cards without authorization ....................................................................................................................... 51
   Payments from bank cards without authorization ...................................................................................................................... 51
   instance-id method ..................................................................................................................................................................... 55
   request-external-payment method .............................................................................................................................................. 56
   process-external-payment method ............................................................................................................................................. 58
Notification of events ....................................................................................................................................................................... 62
     Notification of incoming transfer ............................................................................................................................................... 62
Payment forms for purchasing products and services ................................................................................................................. 66
   Payment forms for purchasing products and services ................................................................................................................ 66
   Searching for business details .................................................................................................................................................... 66
   Form description request ............................................................................................................................................................ 68
   Sending a form or step of a form to the server .......................................................................................................................... 70
   Request for a form description with pre-filled field values ....................................................................................................... 73
   Form description ........................................................................................................................................................................ 74
Index .................................................................................................................................................................................................. 96

Yandex.Money API                                                                                                                                                                          API for Apps
API for Apps     4

               The API for Apps is a tool for using almost all of our service's functions.
               What you can do using the API:

               •   Accept payments — both merchants and individual users. Money can be deducted from any bank card
                   or Wallet.
               •   Get information about users — check the balance and get the history and details of operations.
               •   Get HTTP notifications for automatically processing transfers.
               •   Perform direct debits. Made from the user's wallet by default, or from a bank card by agreement.

               How to get started
               1. Register your app in the Yandex.Money API.
               2. Read the documentation.
               3. Add the new payment feature to the app. To get started quickly, use our SDKs — PHP, Java, Android,
                  ObjC, Python, NodeJS, Ruby, and iOS.
               4. Start accepting payments from bank cards or electronic wallets.

               About payments from bank cards
               The page where the user enters card data is on our side — Yandex.Money has a PCI DSS certificate.
               How it works:

               1. In your app, the user selects "bank card" as the payment method.
               2. You send the user to the page for entering data (on our side). During the payment process, the bank
                  may request additional confirmation (3-D Secure). In this case, we ask the user to enter the password.
               3. After verification by the bank, you deduct the money, and the user returns to the app and sees a page with
                  information about the payment.

               About payments from Wallets
               You only need to get the user's permission once to access the Wallet (standard OAuth).
               How it works:

               1. The app requests the permissions you need. For example, to make recurring direct debits.
               2. The user is sent to our site and confirms access for the app.
               3. Everything is ready. You can deduct money and request data without the participation of the user.

               API for Apps is used by

                         AVITO.ru                    Mamba                Xsolla             Fotostrana      Zen Money

               Any more questions? Send us email at: api@money.yandex.ru

Yandex.Money API                                                                                              API for Apps
API for Apps      5

   Scenarios for receiving payments using Yandex.Checkout
               There are two scenarios for using Yandex.Checkout to receive payments in mobile apps: using Yandex.Checkout
               payment forms, or using the API for Apps. Payment forms are easier to integrate, and they allow you to receive
               payments in all the ways that are available according to your agreement with Yandex.Checkout. However,
               you can only get data from Yandex.Money on the server or by email. The API only lets you receive payments
               from a user's Wallet or from bank cards, but it allows you to process payment information directly in the app.
               You can combine these scenarios.

               Note:

               •   Yandex.Checkout is a payment service for business entities and sole proprietors. To activate it, you need
                   to submit an activation request and sign an agreement with Yandex.Money.
               •   The parameters for accepting payments are independent of the scenario.

               Receiving payments using forms
               This scenario is unique in its simplicity of integration and variety of payment methods. There are several steps
               for using Yandex.Checkout payment forms in a mobile app:

               1. Initializing WebView with POST parameters according to the payment form.
               2. Server-side processing of HTTP requests for order verification and notification of payment (if activation
                  is performed using HTTP notifications with either HTTP Protocol or CMS Module implementation).
               3. Processing redirects from the payment information page when clicking the "Go to the store's site" button
                  (WebView closes).

               Note:
               You can turn on automatically redirecting the user from the successful payment and error pages, a few seconds
               after payment. To find out how to turn on redirection, contact a Yandex.Checkout manager.

Yandex.Money API                                                                                                API for Apps
API for Apps      6

               Tip:
               You can receive payments in a mobile app using WebView, or using a payment form on the site with the payment
               solution protocol for merchants. You can implement your own logic for transmitting payment information from
               the server application to the mobile app, if necessary. You get the successful payment ID in the notification
               of payment.

               Payment process
                 A user initiates a payment (for example, clicks the Pay button when making an order) and is shown the page
                 with information about the payment.

                   Payment from an external (arbitrary) bank card Payment from an account

                   After the user clicks Pay, Yandex.Money sends an order verification request to the store and sends
                   a notification of payment (if required). The HTTP order verification request checks the validity of payment

Yandex.Money API                                                                                               API for Apps
API for Apps      7

                   parameters, and the notification of payment informs the store of successful payment. After payment, the user
                   sees the success or error page.

                   Payment completed successfully                        Payment failed

               Receiving payments using the API for Apps
               Integration using the API for Apps lets you control the payment process within the app, get the payment status
               from the Yandex.Money server, and store user data for future payments. You can use this scenario to receive
               payments in two ways: from a Yandex.Money Wallet or from an arbitrary bank card.
               The integration process depends on the payment method.
               In any case, you first need to register the app in a Yandex.Money Wallet (you can create a Wallet just
               for registration).
               Payments from the Yandex.Money wallet

Yandex.Money API                                                                                                API for Apps
API for Apps      8

               To make a payment this way, the user must log in on the Yandex.Money site. The user can pay from the Wallet
               or using bank cards that are linked to it. To complete the payment, the app must:

               1. Complete authorization on the Yandex.Money server and get an access_token.
               2. Initialize a payment using the request-payment method.
               3. Process the payment using the process-payment method and process the checkOrder and paymentAviso
                  notifications if the store has Yandex.Checkout activated using the HTTP method.

               Payments from bank cards
               For this type of payment, the user doesn't need to register on the Yandex.Money site. The user can pay with
               any bank card. To complete the payment, the app must:

               1. Get the app instance ID.
               2. Initialize a payment using the request-external-payment method.
               3. Use the process-external-payment method to process the payment, and process the checkOrder
                  and paymentAviso notifications if the store has Yandex.Checkout activated via the HTTP method.

               The process of paying with a bank card looks the same as when paying through a payment form (see above).

               Note:
               The payment parameters in the request-payment and request-external-payment methods
               generally match the parameters in payment forms. Exceptions: You don't need to pass shopId
               and paymentType, but you must pass scid in pattern_id. The other parameters are passed the same
               way as for integration with a payment form.

               Note:
               If you have already activated Yandex.Checkout, you don't need to contact your manager and fill out additional
               paperwork. You can use the API for Apps for integration in individual cases, as described in the introduction.

               SDK
                 You can use the libraries for programmatic implementation of the API for Apps:

                   •   Java-SDK
                   •   Android-SDK
                   •   ObjectiveC-SDK

                   All the branches have links to documentation.

Yandex.Money API                                                                                              API for Apps
Application authorization flow 9

   Application authorization flow

       Application authorization flow
               In order to access a user's Yandex.Money account, your application must complete the authorization process.
               The OAuth2 protocol makes authorization secure and convenient. With OAuth2 authorization, applications don't
               need to ask users for their Yandex login and password. Instead, a user grants permission for an application
               to access his account within the restrictions allowed by the user.
               Application authorization in Yandex.Money conforms to the following specifications:

               •   The OAuth 2.0 Authorization Framework
               •   The OAuth 2.0 Authorization Framework: Bearer Token Usage

               Diagram illustrating how an application and a user interact with the Yandex.Money OAuth server:

               Developer steps
               1. The developer registers the application in Yandex.Money.
                   According to the OAuth2 protocol, this is the Registration Request stage. The Yandex.Money service issues
                   the developer a client_id, which is a string type application ID.
               2. The developer embeds this client_id in the application code, declaring it a constant. Then the application
                  can be distributed using any convenient method. The client_id remains constant during the entire
                  application lifecycle.

Yandex.Money API                                                                                              API for Apps
Application authorization flow 10

               How a user authorizes an application
               1. The user initializes authorization of the application for managing his account.
               2. The application sends the Authorization Request to the Yandex.Money server.
               3. Yandex.Money redirects the user to the authentication page.
               4. The user enters his login and password, reviews the list of requested permissions, and either approves
                  or rejects the authorization request.
               5. The application receives an Authorization Response in the form of an HTTP Redirect with either a temporary
                  authorization code or an error code.
               6. The application sends a request for an access token (Access Token Request), using the temporary
                  authorization code in the request.
               7. The response contains the permanent access_token.
               8. The application informs the user of the authorization results.

               Verifying the application's authenticity using a secret word
               The Yandex.Money service provides an additional way to verify that the access token is coming from your
               application.
               To do this, when obtaining the access token (the /oauth/token call), the application passes a secret word
               (client_secret) that is only known to the application.

               Note:
               Security measures based on the secret word are effective only if the token request is sent from the application's
               server, bypassing the user's device or browser.

               Security requirements
               1. All network interactions are transmitted only via HTTPS.
               2. In order to prevent compromise of authorization data, the application must verify the validity of the server
                  SSL certificate and abort the session immediately if validation fails.
               3. Do not store the access token in unencrypted format, for example, as cookies.
               4. Never use the access token in request parameters (GET, POST etc).
               5. The secret word should never be transmitted through the user's device or browser.
               6. The secret word should not be used in any requests other than the request to get a token.

Yandex.Money API                                                                                                 API for Apps
Application authorization flow 11

       App registration
               To register your application in Yandex.Money, follow these steps:

               1. Go to the App registration page. To log in, you must enter the payment password.
               2. Set the application parameters:
                     description
                        The name of your application (for example, “Mobile store”).
                     logo
                        Your application's logo.
                     application_uri
                        Link to the application's or the developer’s website.
                     redirect_uri
                        URI for returning the result of application authorization (see redirect_uri in the OAuth
                        2.0 Authorization Protocol).
                     Use application authenticity verification
                       Specify whether you want to use the secret word for verifying the authenticity of the application (see
                       the description of client_secret in The OAuth 2.0 Authorization Framework).
               3. Click the “Confirm” button.
                     The App data page opens, where you will see the name of your application, its ID (client_id), and,
                     if the corresponding option is selected, the secret word that was generated (client_secret).

                     Caution!
                     The application developer should never openly publish the application's client_id anywhere. Leaking
                     the client_id might provoke "phishing attacks," where applications or sites are launched to get access
                     tokens in your name. If this happens, Yandex.Money will assume that it is receiving requests from your
                     application.
                     To prevent this, you can use the secret word (client_secret), which is only known by the application
                     developer. The application developer should ensure that the secret word (client_secret) is kept
                     confidential.

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

               Tip:
               To request a token, we recommend using the POST method (the equivalent of HTML "form submit"), and UTF-8
               encoding.

               Request format:

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

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

               Example of request parameters:

Yandex.Money API                                                                                               API for Apps
Application authorization flow 12

                   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: money.yandex.ru
                   Content-Type: application/x-www-form-urlencoded
                   Content-Length: 191

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

               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.

               Note:
               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
               Yandex.Money service.

               For the authorization request, the user is redirected to the Yandex.Money 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.
               The authorization result is returned as an HTTP 302 Redirect. The application must process the HTTP Redirect
               response.

               Attention!
               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.

Yandex.Money API                                                                                                       API for Apps
Application authorization flow 13

               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         Description                               Behavior of the service
                   invalid_request                  The request is missing required           Page with the error message text.
                                                    parameters, or parameters have
                                                    unsupported or invalid values.
                   invalid_scope                    The scope parameter is missing, or it     Page with the error message text.
                                                    has an invalid value or a contradiction
                                                    in logic.
                   unauthorized_client              The client_id value is invalid,           Page with the error message text.
                                                    or the application does not have rights
                                                    to request authorization (for example,
                                                    its client_id has been blocked
                                                    by Yandex.Money).
                   access_denied                    Authorization request was declined        Redirect to the application with the error
                                                    by the user.                              code.
               Example of the Yandex.Money response for successful authorization:

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

               Response from Yandex.Money when authorization is declined:

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

               Note:
               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 Yandex.Money server and immediately
               exchange the temporary authorization code for the access token.

Yandex.Money API                                                                                                        API for Apps
Application authorization flow 14

               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.

                    See also
                    Access token request
                    Revoking a token
                    Application authorization flow
                    App registration

       Access token request
               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 Yandex.Money OAuth server. The request must be sent using the POST method.
               Request format:

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

                   code=&client_id=&grant_type=authorization_code&redirect_uri=

               Request example without verifying authenticity:

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

                   code=0DF3343A8D9C7B005B1952D9B933DC56ACB7FED6D3F2590A6FD90EC6391050EDFFCC993D325
                   B41B00F58E5383F37F6831E8F415696E1CF07676EE8D0A3655CDD7C667189DFB69BFDB7116C03293
                   03AB2554290048BAF9B767B4C335BF0E85830AC017AD2F14D97F529893C202D3B2C27A61EE53DC4F
                   B04DAE8E815DE2E3F865F&client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKL
                   MNOPQRSTUVWXYZ01&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: money.yandex.ru
                   Content-Type: application/x-www-form-urlencoded
                   Content-Length: 580

                   code=0DF3343A8D9C7B005B1952D9B933DC56ACB7FED6D3F2590A6FD90EC6391050EDFFCC993D325
                   B41B00F58E5383F37F6831E8F415696E1CF07676EE8D0A3655CDD7C667189DFB69BFDB7116C03293
                   03AB2554290048BAF9B767B4C335BF0E85830AC017AD2F14D97F529893C202D3B2C27A61EE53DC4F
                   B04DAE8E815DE2E3F865F&client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKL
                   MNOPQRSTUVWXYZ01&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fclient
                   %2Eexample%2Ecom
                   %2Fcb&client_secret=NH2FGEYIS57DXVO4CJ4APTQVWWH78JZ140EIMJ5YOLTG0TQV0OIM9WBN1DGR
                   Z3LP9AJK8ROAGMZFELPNK863HPRCF14CLWQXX66DSBHT3Z1X9WDC2I7MNKEWFY9285ARSW57QSWKBYB0
                   263V

               Request parameters:

                   Parameter                         Type                                Description

Yandex.Money API                                                                                               API for Apps
Application authorization flow 15

                   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.

               In response to the request, the Yandex.Money 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                            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 Yandex.Money).
                   invalid_grant                                       The access_token could not be issued. Either
                                                                       the temporary authorization code was not issued
                                                                       by Yandex.Money, 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.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789AB
                   CDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJ
                   KLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQR
                   STUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123"
                   }

               Example of error response:

Yandex.Money API                                                                                                    API for Apps
Application authorization flow 16

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

                   {
                        "error":"invalid_grant"
                   }

               Tip:
               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.

               Note:
               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.

               Attention!
               The token is valid for three years. When the token expires, it is automatically revoked.

                       See also
                       Authorization Request
                       Revoking a token
                       Application authorization flow
                       App registration

       Revoking a token
               The application can revoke an access token that was issued. This means that all permissions that were granted
               to this token will be revoked.
               To do this, send a request to the Yandex.Money OAuth server with the HTTP Authorization header containing
               the token to be revoked.
               The request must be sent using the POST method.
               Request example:

                   POST /api/revoke HTTP/1.1
                   Host: money.yandex.ru
                   Authorization: Bearer
                   410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQR
                   STUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ
                   0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ01234567
                   89ABCDEFGHIJKLMNOPQRSTUVWXYZ0123
                   Content-Length: 0

               In response, the Yandex.Money server returns one of the following HTTP codes:

                   HTTP response code                                  Description
                   200 OK                                              The token was revoked successfully.

Yandex.Money API                                                                                              API for Apps
Application authorization flow 17

                   400 Bad Request                                    HTTP request does not conform to protocol format. Possible
                                                                      reasons: the request can't be parsed; the HTTP
                                                                      Authorization header is missing or has an invalid value.

                   401 Unauthorized                                   The specified token does not exist, or has already been
                                                                      revoked.
               Successful response example:

                   HTTP/1.1 200 OK
                   Content-Length: 0

               Example of error response:

                   HTTP/1.1 400 Bad Request
                   Content-Length: 0

                    See also
                    Authorization Request
                    Access token request
                    Application authorization flow
                    App registration

       Access token scope
               When invoking a protocol operation, you must pass an access token that has the necessary permissions. The list
               of permissions is requested as the value of the scope parameter for an authorize call for OAuth2
               authorization of the application by the user; permissions are separated by a space.
               The possible permissions are listed below:

                   Permission                                         Description
                   account-info                                       To get information about the account status (see the account-
                                                                      info method).
                   operation-history                                  To view the history of account operations (see the operation-
                                                                      history method).
                   operation-details                                  To view details of a particular operation (see the operation-
                                                                      details method).
                   incoming-transfers                                 To accept/cancel incoming transfers with a secret code
                                                                      and held for pickup.
                   payment                                            To make payments to a particular merchant or transfer funds
                                                                      to a particular User account (see the request-payment
                                                                      and process-payment methods).
                   payment-shop                                       To make payments to any merchant accessible via the
                                                                      API (see the request-payment and process-payment
                                                                      methods).
                   payment-p2p                                        To transfer funds to any accounts, phone numbers, or email
                                                                      addresses of other users (see the request-payment
                                                                      and process-payment methods).
                   money-source                                       Available payment methods (see the methods request-
                                                                      payment and process-payment). For more information,
                                                                      see The money-source permission.

Yandex.Money API                                                                                                    API for Apps
Application authorization flow 18

               Restriction:
               The following cannot be used simultaneously in "scope":

               •        payment-p2p permission and payment.to-account permission
               •        payment-shop permission and payment.to-pattern permission

               Tip:
               Some permissions require setting string values that may contain symbols that violate the scope syntax. For such
               symbols, use backslash escaping according to JSON format. For example: \" \\

               Restrictions that apply to permissions
               Restrictions (limits) may be applied to the permissions granted. Limits are specified like this:
                   permission_name.destination.limit

               Restrictions that can be applied to permissions:
               destination condition (the payment recipient)
                 Applies to the permission: payment.

                    Only one of the following conditions can be specified as a value:

                    •     to-pattern(patternId) — Restricts sending payments only using the specified patternId.
                    •     to-account(to) — Restricts transfers of funds only to the account of a specific user. For the recipient
                          ID, you can use an account number, mobile phone number that is linked with the user's account, or the
                          user's email address.

                    Limiting parameters:

                    Parameter                                               Description
                    to                                                      The transfer recipient's account ID, phone number linked
                                                                            to the account, or email. Required parameter.

                    Tip:
                    Mobile phone number as the payee ID.
                    Instead of using the account number as the payee ID, you can use the mobile phone number associated with
                    the account (if the payee has one). The specified phone number must be in the format of the ITU-T E.164
                    Numbering plan of the international telephone service.
                    For Russia, this is the full number starting from 7, without the '+' symbol.
                    For example: 79219990099

                    Tip:
                    Email format.
                    Acceptable ways of formatting email addresses are described in Wikipedia. Keep in mind that email addresses
                    may contain symbols that violate the scope syntax, such as double quotes.

Yandex.Money API                                                                                                      API for Apps
Application authorization flow 19

                   For such symbols, use backslash escaping according to JSON format. For example: \" \\

                   Example for specifying the transfer recipient using an account number:

                   .to-account("41001XXXXXXXX")

                   Example for specifying the transfer recipient using a linked mobile phone number:

                   .to-account("79219990099")

                   Example of specifying the transfer recipient using email:

                   .to-account("username@yandex.ru")

               limit condition (payment limit)
                   limit(duration,sum)

                   Applies to these permissions: payment, payment-shop, payment-p2p.

                   The limit is specified last.
                   Format:

                   •   limit(duration,sum) — Limit to the total amount of payments over a period of time.
                   •   limit(,sum) — Delegation of rights to make a one-time payment for a fixed amount.

                   Parameters:

                   Parameter                                              Value
                   duration                                               Period of time, in days. If omitted, payment can only
                                                                          be made once using the given permission.
                   sum                                                    Total amount for all payments over the period
                                                                          in duration, in the currency used for the account.

                   Tip:
                   The limit condition can be used for delegating one-time payments. The expiration of the permission is the
                   same as for the token. The user cannot change the payment amount.

                   Restriction:
                   In the context of a single scope, it is allowed to specify either only duration-restricted payments, or only
                   one-time payments.

                   Restriction:
                   If scope is set for a one-time payment, then, in addition to the payment permission, only the money-
                   source and account-info permissions can be set; all other permissions are forbidden.

                   Restriction:
                   Regardless of the value of the requested limits, payments can also be subject to restrictions set by
                   Yandex.Money for various types of transactions.

                   Example: payments restricted to 100 rubles and 50 kopecks per day, and the user can change the amount.

Yandex.Money API                                                                                                     API for Apps
Application authorization flow 20

                     .limit(1,100.50)

                     Example: one-time payment of 1000 rubles and the user cannot change the amount.

                     .limit(,1000)

                     By default: limit(1,3000) — 3000 rubles per day and the user can change the amount.

               The money-source permission
               Informs Yandex.Money which payment methods are supported by the application.
               Format:

                   money-source(list_of_payment_methods)

               The requested method for making a payment:

               •      wallet — Payments from a Yandex.Money account.
               •      cards — With the user's bank cards that are linked to the account.

               Default: wallet.

               Restriction:
               Bank cards cannot be used for transferring funds to other users' accounts.

               Example of payment using both a linked bank card and an account:

                   money-source("wallet","card")

               Example of payment using only a linked bank card:

                   money-source("card")

               Example of payment using only an account:

                   money-source("wallet")

                   Examples of values for the scope parameter
                   Permitted to view payment history:
                   account-info operation-history operation-details

                   Permitted to view the account balance and make payments to merchant 123 for up to 1000 rubles per week:
                   account-info payment.to-pattern("123").limit(7,1000)

                   Permitted to make transfers to account XXXX, but no more than 500 rubles over a two-week period:
                   payment.to-account("XXXX").limit(14,500)

                   Permitted to make a one-time transfer to the account linked to phone number ZZZ, in the amount of 500 rubles:
                   payment.to-account("ZZZ","phone").limit(,500)

                   Permitted to make payments from the linked bank card to merchant 123 up to a total of 1000 rubles per week:
                   payment.to-pattern("123").limit(7,1000) money-source("wallet","card")

Yandex.Money API                                                                                                          API for Apps
Protocol overview 21

   Protocol overview

       Request format
               Requests are to be sent via HTTP 1.1 using SSL (HTTPS) to the following address:

                   https://money.yandex.ru/api/

               Requests are authorized in accordance with The OAuth 2.0 Authorization Framework: Bearer Token Usage.
               HTTP requests must have this header:

                   Authorization: Bearer 

               Note:
               The token that is used must have the necessary permissions to execute the requested method with the specified
               set of parameters.

               Security requirements:

               1. All network interactions are transmitted only via HTTPS.
               2. The application should verify the validity of the server's SSL certificate. If the SSL certificate did not pass
                  verification, the session must be aborted immediately to prevent compromising the authorization data.
               3. Do not store the access token in unencrypted format, for example, as cookies.
               4. Never use the access token in request parameters (GET, POST etc).

               Format for request parameters:

               •     Key/value pairs, packed as HTTP 1.1 POST request parameters.
               •     MIME type: application/x-www-form-urlencoded.
               •     Encoding: UTF-8.

               Request example:

                   POST /api/request-payment HTTP/1.1
                   Host: money.yandex.ru
                   Content-Type: application/x-www-form-urlencoded
                   Authorization: Bearer
                   410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQR
                   STUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ
                   0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ01234567
                   89ABCDEFGHIJKLMNOPQRSTUVWXYZ0123

                   param1=value1&param2=value2&param3=value3

                    See also
                    Response format
                    Access token scope
                    Data types

Yandex.Money API                                                                                                  API for Apps
Protocol overview 22

       Response format
               The response is a JSON document in UTF-8 encoding (see The application/json Media Type for JavaScript
               Object Notation (JSON) and the official JSON site). The contents depend on the request results.
               Successful response example:

                   HTTP/1.1 200 OK
                   Content-Type: application/json
                   Content-Length: 51
                   Expires: Thu, 01 Dec 1994 16:00:00 GMT
                   Cache-Control: no-cache

                   {
                           "param1":"value1",
                           "param2":"value2"
                   }

               The response has HTTP headers to forbid proxy servers and local browsers to cache the content.

               Tip:
               The response may contain extra fields not described in this protocol. The application is to ignore them.

               If authorization fails, the server responds with a 4xx HTTP code. Possible reasons for rejection:

               •       The request cannot be parsed.
               •       The request does not include the HTTP Authorization header.
               •       The Authorization header specifies a nonexistent, invalid or expired token.
               •       The token does not have permissions for the requested operation.

               The response contains the WWW-Authenticate header (in accordance with The OAuth 2.0 Authorization
               Framework: Bearer Token Usage).
               When authorization of the request is denied, the following fields are present in the response:

                   Field                                                  Description
                   error                                                  Code of the reason for authorization refusal.
                   error_description                                      Additional text description of the reason for refusal.
               Codes for reasons for authorization refusal:

                   HTTP response code                  Value of the error field                Description
                   400                                 invalid_request                         HTTP request does not conform
                                                                                               to protocol format. Unable to parse
                                                                                               HTTP request, or the
                                                                                               Authorization header is missing
                                                                                               or has an invalid value.
                   401                                 invalid_token                           Nonexistent, expired, or revoked token
                                                                                               specified.
                   403                                 insufficient_scope                      The token does not have permissions
                                                                                               for the requested operation.
               Response example for missing header:

                   HTTP/1.1 400 Bad Request
                   WWW-Authenticate: Bearer error="invalid_request"

               Response example for expired token:

                   HTTP/1.1 401 Unauthorized
                   WWW-Authenticate: Bearer error="invalid_token", error_description="The access
                   token has expired"

Yandex.Money API                                                                                                          API for Apps
Protocol overview 23

               Response example for token without required permissions:

                   HTTP/1.1 403 Forbidden
                   WWW-Authenticate: Bearer error="insufficient_scope", error_description="Payment
                   forbidden by application authorization parameters"

               If a technical error occurs, the server responds with the HTTP code 500 Internal Server Error.
               The application should repeat the request with the same parameters later.

                    See also
                    Request format
                    Access token scope
                    Data types

       Data types
                   Type                                Corresponding JSON type             Description
                   string                              string                              Character string in UTF-8 encoding.
                   amount                              number                              Amount. Fixed-point decimal number
                                                                                           with 2-digit precision.
                   boolean                             boolean                             Logical value, possible values
                                                                                           are true or false.
                   int                                 number                              32-bit signed integer number.
                   long                                number                              64-bit signed integer number.
                   object                              object                              Embedded JSON object.
                   array                               array                               Array of JSON objects.
                   datetime                            string                              Timestamp value conforming to the
                                                                                           specification RFC3339 in the format
                                                                                           YYYY-MM-DDThh:mm:ss.fZZZZZ
                                                                                           (see explanation below).

               Description of the datetime format:

               •     YYYY — Year, always 4 digits.
               •     MM — Month, always 2 digits (for example, 01 for January).
               •     DD — Day of the month, always 2 digits (from 01 to 31).
               •     T — Uppercase letter "T".
               •     hh — Hour, always 2 digits (24-hour format, from 00 to 23).
               •     mm — Minute, always 2 digits (from 00 to 59).
               •     ss — Second, always 2 digits (from 00 to 59).
               •     f — Fraction of a second, from 1 to 6 digits; may be omitted, in which case the preceding dot separator
                     (.) should be omitted as well.
               •     ZZZZZ — Time Zone Offset, mandatory parameter. Can take the values:

                     •     Z — UTC, uppercase letter "Z".
                     •     +hh:mm or -hh:mm – UTC (GMT) offset (indicates that a local time is shown that is either ahead of or
                           behind UTC by the specified number of hours and minutes).

               Example:

Yandex.Money API                                                                                                    API for Apps
Protocol overview 24

                   2011-07-01T19:00:00.000+04:00 — 7 p.m. on July 1, 2011 in the time zone Europe/
                   Moscow (UTC+04:00).

                    See also
                    Date and Time on the Internet: Timestamps
                    Request format
                    Response format
                    Access token scope

Yandex.Money API                                                                         API for Apps
Information about a user's account 25

   Information about a user's account

       account-info method

               Description
               Getting information about the status of the user account.
               Required permissions: account-info

               Input parameters
               None

               Returns
               If successful, returns a JSON document containing the following:

                   Parameter               Type             Description
                   account                 string           User's account number.
                   balance                 amount           User's account balance.
                   currency                string           User's account currency code. Always 643 (ruble of the Russian
                                                            Federation by the ISO 4217 standard).
                   account_status          string           The user's status. Possible values:

                                                            •    anonymous — anonymous account
                                                            •    named — named account
                                                            •    identified — identified account

                   account_type            string           User's account type. Possible values:

                                                            •    personal — user account in Yandex.Money
                                                            •    professional — professional business account
                                                                 in Yandex.Money

                   avatar                  object           Link to the user's avatar. If the user's avatar is not set, the parameter
                                                            is omitted.
                   balance_details         object           Detailed information about the balance. By default, this section
                                                            is omitted. This section appears if there are now or ever have been:

                                                            •    deferred deposits
                                                            •    negative balance
                                                            •    blocked funds

                                                            Details.

                   cards_linked            array            Information about bank cards linked to the account.
                                                            If the account does not have any cards linked to it, the parameter
                                                            is omitted. If the account has at least one card linked to it, the parameter
                                                            contains a list of information about the linked cards.

               Parameters for the avatar object:

                   Parameter               Type             Description
                   url                     string           Link to the user's avatar.

Yandex.Money API                                                                                                         API for Apps
Information about a user's account 26

                   Parameter             Type            Description
                   ts                    datetime        Timestamp of the last change to the avatar.

               Parameters of the balance_details object:

                   Parameter             Type            Description
                   total                 amount          Total account balance.
                   available             amount          Amount available for payments.
                   deposition_pending    amount          The amount of pending deposits. If there are no pending deposits,
                                                         the parameter is omitted.
                   blocked               amount          The amount of funds blocked by authorities. If there are no blocked funds,
                                                         the parameter is omitted.
                   debt                  amount          The amount owed (the negative balance on the account). If the balance
                                                         is positive, this parameter is omitted.
                   hold                  amount          Amount of frozen funds. If there are no frozen funds, the parameter
                                                         is omitted.

               Parameters for the cards_linked object:

                   Parameter             Type            Description
                   pan_fragment          string          Masked card number.
                   type                  string          Card type. May be omitted if unknown. Possible values:

                                                         •   VISA
                                                         •   MasterCard
                                                         •   AmericanExpress
                                                         •   JCB

                   Request example:

                   POST /api/account-info HTTP/1.1
                   Host: money.yandex.ru
                   Authorization: Bearer
                   410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ
                   0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEF
                   GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUV
                   WXYZ0123
                   Content-Type: application/x-www-form-urlencoded
                   Content-Length: 0

                   Response example:

                   {
                     "account": "4100123456789",
                     "balance": 1000.00,
                     "currency": "643",
                     "account_status": "anonymous",
                     "account_type": "personal",
                     "avatar": {
                        "url": "http://avatars.yandex.net/get-yamoney-profile/yamoney-profile-30633298/
                   normal",
                        "ts": "2013-03-13T20:43:00.000+04:00"
                     },
                     "cards_linked": [
                        {
                          "pan_fragment": "510000******9999",
                          "type": "MasterCard"
                        }
                     ]
                   }

Yandex.Money API                                                                                                   API for Apps
Information about a user's account 27

       operation-history method

               Description
               This method allows viewing the full or partial history of operations in page mode. History records are displayed
               in reverse chronological order (from most recent to oldest).
               Required permissions: operation-history.

               Input parameters
                   Parameter                Type               Description
                   type                     string             List of operation types to display (see the table). Types in the list
                                                               are separated by a space. If omitted, all operations are displayed.
                   label                    string             Filtering payments by the label value. Payments are selected that have
                                                               the specified value for the label parameter in the request-payment call.
                   from                     datetime           Output operations from a timestamp (operations that were equal to the
                                                               from value or later than it). If omitted, all operations are displayed.
                   till                     datetime           Output operations to a timestamp (operations that were earlier than
                                                               the till value). If omitted, all operations are displayed.
                   start_record             string             If this parameter is present, displays all operations starting from
                                                               the number start_record. Operations are numbered starting from
                                                               0 (see the note).
                   records                  int                Page size, number of history records in response. Accepted values: from
                                                               1 to 100; by default 30.
                   details                  boolean            Show operation details. By default, false. To display operation details,
                                                               the operation-details permission is required.

               Operation types:

                   Type                     Description
                   deposition               Deposits (income).
                   payment                  Payments (expenditure).
                   incoming-transfers- Unaccepted incoming P2P transfers of any type.
                   unaccepted

               Tip:
               The logic used for filtering history records.
               History records are filtered by the conditions:

               •      type of operation
               •      payment label
               •      time period

               All the conditions are additive, meaning each condition adds further restriction.

Yandex.Money API                                                                                                           API for Apps
Information about a user's account 28

               Rules for selecting data by time period:

               1. If both the from and till conditions are set, records are selected for the time period equal to from
                  (or greater) and less than till.
               2. If only the from condition is set, records are selected that have a time later than or equal to from.
               3. If only the till condition is set, records are selected with a time less than till.
               4. If both the from and till conditions are omitted, records are selected without time restrictions.

               If the operation history contains a large number of records, the list of operations is displayed in page mode.
               The first page of the history is displayed by default. If there are additional pages, the next_record parameter
               appears in the response (this parameter is omitted if there is only a single page). To display the next page of the
               history, repeat the request with the same parameters and add the start_record parameter, specifying
               the value from the next_record parameter of the previous response.

               To get a larger selection of records in the time period, form a request with the from and till conditions,
               get the first page of the history, then form requests for the subsequent pages of the history with the same values
               for the from and till parameters, as well as the start_record parameter with the value that was obtained
               from the next_record parameter in the response for the previous page of the history.

               Returns
               The method returns the following parameters:

                   Parameter                Type             Description
                   error                    string           Error code. Present if an error occurred when executing the request.
                   next_record              string           The number of the first history record on the next page. Present if there
                                                             is another page in the history operations (see Notes).
                   operations               array            List of operations.

               Operation parameters:

                   Parameter                Type             Description
                   operation_id             string           Operation ID.
                   status                   string           Status of the payment (transfer). Accepts the following values:

                                                             •    success — Payment completed successfully.
                                                             •    refused — Payment was declined by the recipient or canceled
                                                                  by the sender.
                                                             •    in_progress — Payment is not yet complete; the transfer has not
                                                                  been accepted by the recipient, or is waiting for the secret code to be
                                                                  entered.

                   datetime                 datetime         Operation timestamp (date and time).
                   title                    string           Brief description of the operation (usually contains the merchant name
                                                             or source of deposit).
                   pattern_id               string           The ID of the pattern used for making the payment. Present only
                                                             for payments.
                   direction                string           Direction of financial transaction. Can take the values:

                                                             •    in (income).
                                                             •    out (expenditure).

                   amount                   amount           Operation amount.

Yandex.Money API                                                                                                         API for Apps
Information about a user's account 29

                   Parameter                    Type             Description
                   label                        string           Payment label. Exists for incoming and outgoing transfers made by other
                                                                 Yandex.Money users that had the label parameter set for the request-
                                                                 payment call.
                   type                         string           The type of operation.

               Possible types of operations:

                   Type                                                      Description
                   payment-shop                                              Outgoing payment to a merchant
                   outgoing-transfer                                         Any type of outgoing P2P transfer
                   deposition                                                Credit
                   incoming-transfer                                         Incoming transfer or deferred transfer.
                   incoming-transfer-protected                               Incoming transfer with a secret code.

               The incoming-trasfer and incoming-trasfer-protected types of operations can be accepted
               using incoming-trasfer-accept, and rejected using incoming-trasfer-reject.

               Tip:
               If the value of the details input parameter is set to true, the response will also contain operation-details
               output parameters for operations.

               Operation processing error codes:

                   Code                                                      Description
                   illegal_param_type                                        Invalid value for the type parameter.
                   illegal_param_start_record                                Invalid value for the start_record parameter.
                   illegal_param_records                                     Invalid value for the records parameter.
                   illegal_param_label                                       Invalid value for the label parameter.
                   illegal_param_from                                        Invalid value for the from parameter.
                   illegal_param_till                                        Invalid value for the till parameter.
                   all other values                                          Technical error; repeat the operation again later.

               Note:
               If the operation history contains a large number of records, the list of operations is displayed in page mode.
               The first page of the history is displayed by default. If there are additional pages, the next_record parameter
               appears in the response (this parameter is omitted if there is only a single page).
               To display the next page of the history, repeat the request with the same parameters and add the start_record
               parameter, specifying the value from the next_record parameter of the previous response.

                   Requesting complete history
                   Example of requesting the complete history:

Yandex.Money API                                                                                                           API for Apps
You can also read
Next slide ... Cancel