Yandex.Money API - API for Apps 13.09.2018

Yandex.Money API - API for Apps 13.09.2018

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

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 API for Apps Yandex.Money API API for Apps 4

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. API for Apps Yandex.Money API API for Apps 5

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 API for Apps Yandex.Money API API for Apps 6

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 API for Apps Yandex.Money API API for Apps 7

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. API for Apps Yandex.Money API API for Apps 8

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. Application authorization flow Yandex.Money API API for Apps 9

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. Application authorization flow Yandex.Money API API for Apps 10

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: Application authorization flow Yandex.Money API API for Apps 11

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.

Application authorization flow Yandex.Money API API for Apps 12

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 parameters, or parameters have unsupported or invalid values. Page with the error message text.

invalid_scope The scope parameter is missing, or it has an invalid value or a contradiction in logic.

Page with the error message text. unauthorized_client The client_id value is invalid, or the application does not have rights to request authorization (for example, its client_id has been blocked by Yandex.Money). Page with the error message text. access_denied Authorization request was declined by the user. Redirect to the application with the error code. Example of the 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.

Application authorization flow Yandex.Money API API for Apps 13

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=0DF3343A8D9C7B005B1952D9B933DC56ACB7FED6D3F2590A6FD90EC6391050EDFFCC99 3D325 B41B00F58E5383F37F6831E8F415696E1CF07676EE8D0A3655CDD7C667189DFB69BFDB7116C 03293 03AB2554290048BAF9B767B4C335BF0E85830AC017AD2F14D97F529893C202D3B2C27A61EE5 3DC4F B04DAE8E815DE2E3F865F&client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFG HIJKL MNOPQRSTUVWXYZ01&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fc lient %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=0DF3343A8D9C7B005B1952D9B933DC56ACB7FED6D3F2590A6FD90EC6391050EDFFCC99 3D325 B41B00F58E5383F37F6831E8F415696E1CF07676EE8D0A3655CDD7C667189DFB69BFDB7116C 03293 03AB2554290048BAF9B767B4C335BF0E85830AC017AD2F14D97F529893C202D3B2C27A61EE5 3DC4F B04DAE8E815DE2E3F865F&client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFG HIJKL MNOPQRSTUVWXYZ01&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fc lient %2Eexample%2Ecom %2Fcb&client_secret=NH2FGEYIS57DXVO4CJ4APTQVWWH78JZ140EIMJ5YOLTG0TQV0OIM9WB N1DGR Z3LP9AJK8ROAGMZFELPNK863HPRCF14CLWQXX66DSBHT3Z1X9WDC2I7MNKEWFY9285ARSW57QSW KBYB0 263V Request parameters: Parameter Type Description Application authorization flow Yandex.Money API API for Apps 14

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.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456 789AB CDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDE FGHIJ KLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQR STUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123" } Example of error response: Application authorization flow Yandex.Money API API for Apps 15

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.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQR STUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTU VWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 34567 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.

Application authorization flow Yandex.Money API API for Apps 16

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. Application authorization flow Yandex.Money API API for Apps 17

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.

Application authorization flow Yandex.Money API API for Apps 18

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. Application authorization flow Yandex.Money API API for Apps 19

.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") Application authorization flow Yandex.Money API API for Apps 20

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.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQR STUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTU VWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 34567 89ABCDEFGHIJKLMNOPQRSTUVWXYZ0123 param1=value1&param2=value2&param3=value3 See also Response format Access token scope Data types Protocol overview Yandex.Money API API for Apps 21

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" Protocol overview Yandex.Money API API for Apps 22

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: Protocol overview Yandex.Money API API for Apps 23

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 Protocol overview Yandex.Money API API for Apps 24

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. Information about a user's account Yandex.Money API API for Apps 25

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.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV 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" } ] } Information about a user's account Yandex.Money API API for Apps 26

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 Unaccepted incoming P2P transfers of any type. 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.

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

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. Information about a user's account Yandex.Money API API for Apps 28

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: Information about a user's account Yandex.Money API API for Apps 29

POST /api/operation-history HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 9 records=3 Example request for the next pages of the payment history: POST /api/operation-history HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 40 type=payment&records=20&start_record=120 Example response for the complete history: { "next_record": "4", "operations": [ { "operation_id": "1234567", "status": "success", "pattern_id": "2904", "direction": "out", "amount": 500.00, "datetime": "2011-07-11T20:43:00.000+03:00", "title": "Payment for ADSL access to company XXX", "type": "payment-shop" }, { "operation_id": "1234568", "status": "success", "pattern_id": "2901", "direction": "out", "amount": 300.00, "datetime": "2011-07-10T20:43:00.000+03:00", "title": "Deposit to mobile phone account YYY", "type": "payment-shop" }, { "operation_id": "1234569", "status": "success", "direction": "in", "amount": 1000.00, "datetime": "2011-07-10T20:40:00.000+03:00", "title": "Bank ZZZ, deposit", "type": "deposit" } ] } Example response with details on operations when paying a merchant: Information about a user's account Yandex.Money API API for Apps 30

{ "next_record": "2", "operations": [ { "operation_id": "1234567", "status": "success", "pattern_id": "2904", "direction": "out", "amount": 500.00, "datetime": "2011-07-11T20:43:00.000+04:00", "title": "Payment for ADSL access to company XXX", "details": "Prepayment for ADSL internet access to company XXX\nSubscriber account number: \n1234567/89\nCredited amount: 500.00\nTransaction number: 2000002967767", "type": "payment-shop" } ] } Example response with details of the operation for an outgoing transfer to another user: { "next_record": "2", "operations": [ { "operation_id": "1234567", "status": "success", "pattern_id": "p2p", "direction": "out", "amount": 50.25, "datetime": "2011-07-11T20:43:00.000+04:00", "title": "Transfer to account 4100123456789", "recipient": "4100123456789", "recipient_type": "account", "message": "Buy bagels", "comment": "Transfer to Yandex.Money user", "codepro": false, "details": "Recipient account:\n4100123456789\nAmount: 50.00 RUB", "type": "outgoing-transfer" } ] } Example response for invalid parameter: { "error": "illegal_param_type" } operation-details method Description Provides detailed information about a particular operation from the history.

Required permissions: operation-details.

Input parameters Parameter Type Description operation_id string Operation ID. The value of the parameter should be set like the value of the operation_id parameter from the operation-history method response; if the buyer's account history is being requested, it should be like the payment_id value from the process-payment method response. Information about a user's account Yandex.Money API API for Apps 31

Returns The method returns the following parameters: Parameter Type Description error string Error code, present only if an error occurred. operation_id string Operation ID.

The value of the parameter corresponds to either the value of the operation_id parameter from the operation-history response, or, if the buyer's account history is being requested, the value of the payment_id field from the process-payment response. status string Status of the payment (transfer). The parameter value matches the value of the status field in the response to the operation-history method. pattern_id string Payment Pattern ID. Present only for payments. direction string Direction of financial transaction. Can take the values: • in (income).

• out (expenditure). amount amount Amount of the operation (amount deducted from the account). amount_due amount Amount to receive. Present for outgoing transfers to other users. fee amount Commission amount. Present for outgoing transfers to other users. datetime datetime Operation timestamp (date and time). title string Brief description of the operation (usually contains the merchant name or source of deposit). sender string Account number that funds were transferred from. Present for incoming transfers from other users.

recipient string ID of the transfer recipient. Present for outgoing transfers to other users.

recipient_type string Type of ID used for the transfer recipient. Present for outgoing transfers to other users. message string Message for the transfer recipient. Present for transfers from other users. comment string Comments on the transfer or deposit. Present in the history of the transfer sender or the deposit recipient. codepro boolean The transfer is protected by a secret code. Present for transfers from other users.

protection_code string Secret code. Present for outgoing transfers that have a secret code. expires datetime Date and time when the secret code expires. Present for incoming and outgoing transfers from/to other users that have a secret code. answer_datetime datetime Date and time when a transfer protected by a secret code was accepted or canceled. Present for incoming and outgoing transfers that have a secret code. If the transfer has not yet been accepted or refused by the recipient, this field is omitted.

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.

details string Detailed payment description. String in any format that may contain any symbols or line feeds. type string The type of operation. For possible types of operations, see the description of the operation-history method. digital_goods object Data about a digital product (PIN codes and bonuses for games, iTunes, XBox, etc). This field is present for a successful payment to merchants of digital goods. For a description of the format, see the section Digital goods.

For outgoing transfers to other users, the ID type for the transfer recipient is present: Code Description Information about a user's account Yandex.Money API API for Apps 32

account Recipient's account number in Yandex.Money phone Recipient's linked mobile phone number email Recipient's email address If an error occurs, its code is returned: Code Description illegal_param_operation_id Invalid value for the operation_id parameter. all other values Technical error; call the method again later. Request example: POST /api/operation-details HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 20 operation_id=1234567 Response example for payment to a merchant: { "operation_id": "1234567", "status": "success", "pattern_id": "2904", "amount": 500.00, "direction": "out", "datetime": "2011-07-11T20:43:00.000+04:00", "title": "Payment for ADSL access to the company My Provider", "details": "Prepayment for ADSL internet access to the company ООО \"XXX\"\nSubscriber account number: \n1234567/89\nAmount: 500.00\nTransaction number: 2000002967767", "type": "payment-shop" } Example response for an outgoing transfer to another user: { "operation_id": "1234567", "status": "success", "pattern_id": "p2p", "direction": "out", "amount": 50.25, "datetime": "2011-07-11T20:43:00.000+04:00", "title": "Transfer to account 4100123456789", "recipient": "4100123456789", "recipient_type": "account", "message": "Buy bagels", "comment": "Transfer from Yandex.Money user", "codepro": false, "details": "Recipient account:\n4100123456789\nAmount: 50.00 RUB", "type": "payment-shop" } Response example for nonexistent operation request: { "error": "illegal_param_operation_id" } Information about a user's account Yandex.Money API API for Apps 33

Payments from the Yandex.Money wallet Payments from the Yandex.Money wallet General information Payments from a user's wallet via the API are used for: • Payment of goods and services and transfers to other users from the account or associated bank card. • Making scheduled payments and one-click payments. • Processing incoming deferred transfers and transfers with a secret code. Payment scenarios using a Yandex.Money wallet: 1. Payments are processed based on the Payment Pattern with user parameters specified. Each merchant has its own set of user parameters. The application must show the user (buyer) a form requesting the payment parameters that are required by this merchant, such as the payment amount, phone number, contract number, and so on.

2. The application sends a payment request containing the Payment Pattern ID and the parameters entered by the user. The Yandex.Money server checks the payment parameters and verifies that payments can be made to the merchant, then returns the payment request ID and additional information about the payment. 3. The application shows the payment information to the buyer, and the buyer is to approve or reject the payment. 4. If the buyer confirmed the payment, the application sends a request to confirm payment specifying the ID of the request received earlier using the request-payment method.

Note: 1.

The funds are withdrawn from the buyer's account when the process-payment method is called. 2. If the process-payment call is repeated with the same parameters, the method returns the state of the previous call. 3. If the connection is lost or times out, or there are other network problems, the application must repeat the request with the same parameters. Possible types of payment: • Purchase from a merchant. • Transfer of funds to other user accounts. • Accepting incoming transfers (with a secret code or deferred transfers). • Refusing incoming transfers (with a secret code or deferred transfers).

• Topping up a mobile phone account.

• Test payments for debugging your application. Payments from the Yandex.Money wallet Yandex.Money API API for Apps 34

request-payment method Description Creates a payment, checks parameters and verifies that the merchant can accept the payment, or that funds can be transferred to a Yandex.Money user account. Permissions required for making a payment to a merchant: payment.to-pattern (“Payment Pattern”) or payment- shop. Permissions required for transferring funds to the accounts of other users: payment.to-account (“payee ID,” “ID type”) or payment-p2p.

Arguments for making a payment to a merchant The parameters for making a payment to a merchant are defined by the counterparty when connecting to Yandex.Checkout. Additional information about payment parameters is provided in the payment solution protocol for merchants and integration scenarios.

Parameter Type Description pattern_id string Payment Pattern ID. Corresponds to the merchant's scid (payment form number). * string Payment Pattern parameters required by the merchant. Arguments for transferring funds to the accounts of other users Parameter Type Description pattern_id string Constant value: p2p. to string ID of the transfer recipient (account number, phone number, or email). amount amount Amount to pay (how much the sender will pay). amount_due amount Amount to be received (credited to the receipient's account after payment).

comment string Payment comment, displayed in the sender's history.

message string Comments on the transfer (displayed to the recipient). label string Payment label. Optional parameter. codepro boolean The true value indicates that the transfer is protected by a secret code. Omitted by default (normal transfer). hold_for_pickup boolean Indicates that deferred transfer (sending a transfer and holding it until it can be credited) is allowed. If the parameter is present and is set to true, this is deferred transfer mode.

expire_period int Number of days during which: • A transfer recipient can enter the secret code and receive the transfer to the account. • A deferred transfer recipient can receive the transfer. The parameter value must be between 1 and 365. Optional parameter. By default, 1. Payments from the Yandex.Money wallet Yandex.Money API API for Apps 35

Tip: The transfer amount is credited to the recipient, minus the transfer commission. The sender can set only one of the following parameters: • amount — The amount for the sender to pay (includes the service's commission).

• amount_due — The received amount that will be credited to the recipient's amount. Tip: After sending "request-payment", the user can be shown the commission for the payment. The response to the request will show the contract_amount. Use this formula to calculate the commission: Commission = contract_amount — amount_due The commission is rounded to the kopek (two decimal points). A commission that is less than one kopek is always rounded up to one kopek.

Tip: Any transfer can have a payment label assigned to it. A payment label is a type of ID that is assigned by the application. As a result, you can select transfers in the history using a certain label. For example, you can use a code or an item ID from your application as a payment label. Labels up to 64 symbols long are allowed. Label values are case-sensitive. Input parameters for mobile phone service payment Parameter Type Description pattern_id string Constant value: phone-topup. phone-number string Phone number in ITU-T E.164 format: the full number, starting with 7. Only numbers from mobile service providers in Russia are supported.

Example: 79219990099 amount amount Payment amount. A fee can be subtracted from this amount; the fee depends on the operator.

Tip: The phone number in ITU-T E.164 format is a string of digits up to 15 symbols long representing the full international number of the user's phone, without the '+' sign. For example, the phone number +7(921)999-00-99 is written as 79219990099 Test payment Use a test payment to check how your application works, without making real payments. In testing mode, you can make any type of payment by adding debugging parameters to the method parameters: Parameter Type Description test_payment boolean Indicates a test payment if the value of the field is true. Payments from the Yandex.Money wallet Yandex.Money API API for Apps 36

Parameter Type Description test_card string Optional field. Indicates there is a test bank card if the value of the field is available. test_result string Desired result of the test payment. Possible values: • success — Completed successfully. • Error code from the table — The method returns the specified error code. • Other value — The method returns the error illegal_params. Tip: The Yandex.Money server checks all the parameters of a method and can return an error if these parameters are invalid, regardless of the value of the test_result parameter.

Returns The method returns the following parameters: Parameter Type Description status string Operation result code (see the table).

error string Operation processing error code (additional description for the status field). Present only for errors. money_source object Payment methods available to the application (see Available payment methods). Present only on success. request_id string ID of the payment request. Present only on success. contract_amount amount The amount to deduct from the account in the payer's account currency (how much the user will pay including the commission). Present when the method was completed successfully or for the error not_enough_funds.

balance amount Current balance on the user's account. Present if the following conditions are met: • The method was executed successfully. • The access token has the account-info permission. recipient_account_statu s string The user's status. Possible values: • anonymous — Anonymous account. • named — Named account. • identified — Identified account. recipient_account_type string Recipient's account type. This parameter is present if the method was successfully executed when transferring funds to another Yandex.Money user account.

protection_code string The secret code for this transfer.

The parameter is present if the codepro=true input parameter was set. A string of 4 decimal digits that may include leading zeros. The parameter must be processed as a string. account_unblock_uri string The address to send the user to in order to unblock an account. This field is present if the account_blocked error occurred. ext_action_uri string The address to send the user to in order to complete necessary actions if the ext_action_required error occurs.

Payments from the Yandex.Money wallet Yandex.Money API API for Apps 37

Operation processing result codes: Code Description success Success. refused Payment refused; the reason is explained in the error field. Final state. hold_for_pickup The payment recipient was not found, and funds will be sent when requested. Success. If an error occurred while processing the transaction, the error code is returned: Code Description illegal_params Required payment parameters are either missing or have invalid values. illegal_param_label Invalid value for the label parameter.

illegal_param_to Invalid value for the to parameter. illegal_param_amount Invalid value for the amount parameter. illegal_param_amount_due Invalid value for the amount_due parameter. illegal_param_comment Invalid value for the comment parameter. illegal_param_message Invalid value for the message parameter. illegal_param_expire_period Invalid value for the expire_period parameter. not_enough_funds The payer's account does not have sufficient funds to make the payment. Additional funds should be credited to the account, and a new payment will need to be processed.

payment_refused The merchant refused to accept the payment (for example, the user tried to purchase an item that is not in stock). payee_not_found The transfer recipient was not found. The specified account does not exist, or a phone number or email address was specified that is not linked to a user account or payee. authorization_reject Authorization of the payment was refused. Possible reasons: • A transaction with the current parameters is forbidden for this user. • The user did not accept the User Agreement for the Yandex.Money service. limit_exceeded One of the operation limits was exceeded: • For the total amount of operations for the access token granted.

• For the total amount of operations over a period of time for the access token granted.

• Yandex.Money restrictions for various types of operations. account_blocked The user's account has been blocked. In order to unblock the account, the user must be redirected to the address specified in the account_unblock_uri field. ext_action_required This type of payment cannot be made at this time. To be able to make these types of payments, the user must go to the page with the ext_action_uri address and follow the instructions on that page. This may be any of the following actions: • Entering identification data. • Accepting the offer. • Performing other actions according to the instructions.

all other values Technical error; repeat the operation again later. Payments from the Yandex.Money wallet Yandex.Money API API for Apps 38

Note: When processing a payment, Yandex.Money normally connects to the merchant webserver, which is why the method response time may take up to 30 seconds. While the request-payment method is being processed, the application should display an informational message to the buyer, such as "waiting for a response from the merchant". Note: Successful execution of the request-payment method does not guarantee that the payment process will be completed successfully, since payment authorization is performed when calling the process-payment method.

Available payment methods The money_source field in the response contains a list of methods available for making this payment.

Each method contains a set of attributes. If none of the methods described below can be used for the payment, the money-source field will be empty. Possible payment methods: Code Description wallet Payment using funds on the user's account. cards Payment using bank cards that are linked to the account. Attributes of the method of payment from the user's account: Attribute Type Description allowed boolean Flag indicating whether this payment method is allowed by the user. Attributes of the method of payment with a bank card: Attribute Type Description allowed boolean Flag indicating whether this payment method is allowed by the user.

csc_required boolean Indicates whether the CVV2/CVC2 code is required for authorizing payment using a bank card.

item object Description of the bank card linked to the account. Parameters for the bank card description: Attribute Type Description id string Identifier of the bank card linked to the account. It must be specified in the process-payment method in order to complete payment using the selected card. pan_fragment string A fragment of the bank card number. This field is only present for a linked bank card. May be omitted if unknown. type string Card type. May be omitted if unknown. Possible values: • Visa • MasterCard • American Express • JCB If the method is available for the given merchant and allowed by the user, the response will have the method name and the "allowed" flag set to "true".

Payments from the Yandex.Money wallet Yandex.Money API API for Apps 39

For example: "wallet": { "allowed": true }, "cards": { "allowed": true, "csc_required": true, "items": [ { "id": "card-385244400", "pan_fragment": "5280****7918", "type": "MasterCard" }, { "id": "card-385244401", "pan_fragment": "4008****7919", "type": "Visa" } ] } If the method is available but is not allowed by the user, the response will have the method name and the "allowed" flag set to "false".

For example: "wallet": { "allowed": false }, "cards": { "allowed": false } Tip: The application can request additional permissions for making payments.

The request for additional permissions is made by repeating the request for user authorization of the application. Transfer recipient data When a transfer to another user account is requested, the request-payment method returns the following fields: Code Description recipient_account_statu s The user's status. Possible values: • anonymous — Anonymous account. • named — Named account. • identified — Identified account. recipient_account_type Recipient's account type. Possible values: • personal — User account in Yandex.Money. • professional — Professional business account in Yandex.Money. Examples Request example for paying for mobile phone service: Payments from the Yandex.Money wallet Yandex.Money API API for Apps 40

POST /api/request-payment HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 61 pattern_id=phone-topup&phone-number=79219990099&amount=300.00 Request example for transferring funds to another user account: POST /api/request-payment HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 234 pattern_id=p2p&to=41001101140&amount=1000.00&message=%D0%9D %D0%B0%D0%B7%D0%B2%D0%B0%D0%BD%D0%B8%D0%B5%20%D0%BF%D0%BB %D0%B0%D1%82%D0%B5%D0%B6%D0%B0&comment=%D0%A1%D0%BE%D0%BE%D0%B1%D1%89%D0%B5 %D0%BD %D0%B8%D0%B5%20%D0%BF%D0%BE%D0%BB%D1%83%D1%87%D0%B0%D1%82%D0%B5%D0%BB%D1%8E Request example for transferring funds to another user account using a linked phone number: POST /api/request-payment HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 256 pattern_id=p2p&to=79219990099&identifier_type=phone&amount=1000.00&message= %d0%97%d0%b0+ %d0%b2%d0%ba%d1%83%d1%81%d0%bd%d1%8b%d0%b9+%d0%b1%d1%83%d0%b1%d0%bb%d0%b8%d 0%ba&comment= %d0%ba%d1%83%d0%bf%d0%b8%d1%82%d0%b5+%d0%b1%d1%83%d0%b1%d0%bb%d0%b8%d0%ba%d 0%b8! Successful payment response example: { "status": "success", "wallet": { "allowed": true }, "cards": { "allowed": true, "csc_required": true, "items": [ { "id": "card-385244400", "pan_fragment": "5280****7918", "type": "MasterCard" }, { "id": "card-385244401", "pan_fragment": "4008****7919", "type": "Visa" } ] }, "request_id": "1234567", "contract": "Payment for services provided by Superphone Inc, phone number +7-9xx-xxx- xx-xx, amount 300.00 RUB", "balance": 1000.00 } Response example for refusal: Payments from the Yandex.Money wallet Yandex.Money API API for Apps 41

{ "status": "refused", "error": "payment_refused", "error_description": "Subscriber does not exist" } See also process-payment method Access token scope process-payment method Description Confirms a payment that was created using the request-payment method. Specifies the method for making the payment. Input parameters Parameter Type Description request_id string Payment request ID assigned by Yandex.Money, copied from the request- payment response. money_source string The requested method for making a payment: • wallet — using funds on the user's account • ID linked to the card's account (value of the id field in the bank card description) Default: wallet csc string Card Security Code, the CVV2/CVC2 code of the user's linked bank card.

This parameter should be set only if payment is being made using a linked bank card.

ext_auth_success_ur i string Address of the page to return to when card payment has been successfully authenticated using 3-D Secure technology. Shown if the application supports 3-D Secure authentication. Required parameter for this type of authentication. ext_auth_fail_uri string Address of the page to return to when card payment has failed authentication using 3-D Secure technology. Shown if the application supports 3-D Secure authentication. Required parameter for this type of authentication. Test payment Use a test payment to check how your application works, without making real payments.

In testing mode, you can make any type of payment by adding debugging parameters to the method parameters: Parameter Type Description test_payment string Indicates a test payment if the value of the field is true. test_card string Optional field. Indicates there is a test bank card if the value of the field is available.

Payments from the Yandex.Money wallet Yandex.Money API API for Apps 42

Parameter Type Description test_result string Desired result of the test payment; acceptable values: • success — Completed successfully. • Error code from the table — the method returns the specified error code • Other value — the method returns the error authorization_reject Tip: The Yandex.Money server checks all the parameters of a method (regardless of the value of the test_result parameter) and can return an error if these parameters are invalid. Returns The method returns the following parameters: Parameter Type Description status string Operation result code (see the table).

error string Operation processing error code (additional description for the status field). Present only for errors.

payment_id string Processed payment ID. Present only on success. This parameter corresponds to the operation-id parameter in operation-history and operation-details for the payer's history. balance amount Balance left on the user account after processing the payment. Present only if the following conditions are met: • The method was executed successfully. • The access token has the account-info permission. invoice_id string The merchant's transaction number in Yandex.Money. Present when payment to the merchant has been completed successfully.

payer string Payer's account number. Present when funds were successfully transferred to the account of another Yandex.Money user.

payee string Account number of the user receiving the payment. Present when funds were successfully transferred to the account of another Yandex.Money user. credit_amount amount The amount credited to the payee's account. Present when funds were successfully transferred to the account of another Yandex.Money user. account_unblock_uri string The address to send the user to in order to unblock an account. This field is present if the account_blocked error occurred.

hold_for_pickup_lin k string A link to the deferred transfer when sending it via Yandex.Mail. The field is present if the value is known. acs_uri string Address of the 3-D secure bank card authentication page on the issuing bank's side. This field is present if 3-D Secure authentication is required in order to complete a transaction using a bank card. acs_params object Authentication parameters for 3-D Secure technology in the form of a name-value collection. This field is present if 3-D Secure authentication is required in order to complete a transaction using a bank card. next_retry long Recommended time interval to wait before repeating a request, in milliseconds.

This field is present when status=in_progress digital_goods object Data about a digital product (PIN codes and bonuses for games, iTunes, XBox, etc). This field is present for a successful payment to merchants of digital goods.

Payments from the Yandex.Money wallet Yandex.Money API API for Apps 43

Operation processing result codes: Code Description success Success (payment processed). Final state. refused Payment processing was refused. The reason for refusal is returned in the error field. Final state. in_progress Payment authorization was not completed. The application should repeat the request with the same parameters later. ext_auth_required In order to complete authorization of payment by card, additional authentication using 3- D Secure technology is required. all other values The payment status is unknown.

The application should repeat the request with the same parameters later.

Tip: The method response may return other internal fields that do not need to be processed. If an error occurred while processing the transaction, the error code is returned: Code Description contract_not_found There is no existing unconfirmed payment with the specified request_id. not_enough_funds The payer's account does not have sufficient funds to make the payment. Additional funds should be credited to the account, and a new payment will need to be processed. limit_exceeded One of the operation limits was exceeded: • For the total amount of operations for the access token granted. • For the total amount of operations over a period of time for the access token granted.

• Yandex.Money restrictions for various types of operations. money_source_not_available The requested payment method (money_source) is not available for this payment. illegal_param_csc The csc parameter has a missing or invalid value. payment_refused The payment was refused. Possible reasons: • The merchant refused to accept the payment (checkOrder request). • The transfer to a Yandex.Money user is not possible (for example, the recipient's wallet has reached the maximum amount allowed). authorization_reject Authorization of the payment was refused. Possible reasons: • The bank card expired.

• The issuing bank refused to perform the transaction for the card.

• Exceeds the limit for this user. • A transaction with the current parameters is forbidden for this user. • The user did not accept the User Agreement for the “Yandex.Money” service. account_blocked The user's account has been blocked. In order to unblock the account, the user must be redirected to the address specified in the account_unblock_uri field. illegal_param_ext_auth_succ ess_uri The ext_auth_success_uri parameter has a missing or invalid value. illegal_param_ext_auth_fail _uri The ext_auth_fail_uri parameter has a missing or invalid value. Payments from the Yandex.Money wallet Yandex.Money API API for Apps 44

Code Description all other values Authorization of the payment was refused. The application should make a new payment request later. Note: The time required for processing a payment using a linked bank card (money_source=card) depends on how long it takes the card's issuing bank to handle the transaction. In addition, Yandex.Money may connect to the merchant's server, and the response time likewise affects the total time for authorizing the payment. If payment authorization continues for more than 1 minute, the process-payment method returns the results code of the in_progress operation. The application should repeat the process-payment method call with the same parameters once a minute, until the final response is received (status should have the value either success or refused).

Caution! If no response was received, the payment status is unknown. It is just as likely that the payment was accepted as that it was refused. To determine the payment status, repeat the process-payment call with the same parameters. Tip: Conditions for processing a payment using a linked bank card: • The user's Yandex.Money account has a bank card linked to it. • The user granted permission for the application to use this bank card for payments. • The payment is being made to a merchant.

• The merchant is able to accept payments using bank cards. 3-D Secure authentication of payment using a linked bank card If payment is made using a bank card, additional buyer verification may be required using 3-D secure technology.

Payment scenario with 3-D Secure authentication: • request-payment is called with payment parameters • process-payment is called with money-source=card, csc code, ext_auth_success_uri, and ext_auth_fail_uri • process-payment returns status=ext_auth_required, acs_uri, and acs_params • the application should open the browser and make a POST request to the acs_uri address with acs_params parameters as application/x-www-form-urlencoded (the same as "HTML form submit") • the client is authenticated using the issuing bank's process, then sent by HTTP 302 Redirect to either ext_auth_success_uri or ext_auth_fail_uri, depending on the result • the application should repeat the process-payment call, specifying only a single parameter, request_id • process-payment returns status=success or refused.

Data about digital goods For a successful payment to a merchant of digital goods, the response contains the digital_goods field, which has a list of goods and a list of bonuses.

Payments from the Yandex.Money wallet Yandex.Money API API for Apps 45

Data about a digital product or bonus: Parameter Type Description merchantArticleId string Product identifier in the seller's system. Present only for products. serial string Serial number of the product (the open part of the PIN code, activation code, or login). secret string Secret for the digital product (the closed part of the PIN code, activation code, password, or download link). Example of digital goods: "digital_goods": { "article": [ { "merchantArticleId": "1234567", "serial": "EAV-0087182017", "secret": "87actmdbsv" }, { "merchantArticleId": "1234567", "serial": "2000012", "secret": "gjhkgjsuurtrghxchfhjkrwetuertrehtthh" }, { "merchantArticleId": "1234567", "serial": "2000013", "secret": "77788sfs7fd89g89dfg77778dfgdjkert789" } ], "bonus": [ { "serial": "XXXX-XX-XX", "secret": "0000-1111-2222-3333-4444" } ] } Examples Request example for payment from a user's account: POST /api/process-payment HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 18 request_id=1234567 Request example for payment with the user's linked bank card: POST /api/process-payment HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 44 request_id=1234567&money_source=card&csc=123 Response example if payment authorization was not completed: Payments from the Yandex.Money wallet Yandex.Money API API for Apps 46

{ "status": "in_progress" } Request example for payment with a bank card by an application that supports 3-D Secure: POST /api/process-payment HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 164 request_id=1234567&money-source=card&csc=123&ext_auth_success_uri=http%3A%2 F %2Fclient.example.com%2Fsuccess&ext_auth_fail_uri=http%3A%2F%2Fclient.examp le.com%2Ffail Request example when repeating the request for payment with a bank card by an application after passing 3-D Secure authentication: POST /api/process-payment HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 18 request_id=1234567 Response example for successful authorization of the payment: { "status": "success", "payment_id": "2ABCDE123456789", "balance": 1000.00 } Response example for refusal: { "status": "refused", "error": "not_enough_funds" } Response example if payment authorization was not completed: {"status": "in_progress"} Response example when 3-D Secure authentication is required.

{ "status": "ext_auth_required", "acs_uri": "https://acs.alfabank.ru/acs/PAReq", "acs_params": { "MD": "723613-7431F11492F4F2D0", "PaReq": "eJxVUl1T2zAQ/ CsZv8f6tCR7LmLSGiidJjAldMpTR7XVxAN2gmynSX59JeNAebu9O93u7QkuDvXzZG9dW22bWURi HE1sU2zLqlnPo ofV1VRFFxpWG2dtfm+L3lkNC9u2Zm0nVTmLVvn9r7v5d/uS/UkYt4b8tjibUiGVxazICMeSSkmt wBmlhYw=" } } See also request-payment method Access token scope Payments from the Yandex.Money wallet Yandex.Money API API for Apps 47

incoming-transfer-accept method Description Accepting incoming transfers with a secret code and deferred transfers. There is a limit on the number of attempts to accept an incoming transfer with a secret code. When the allowed number of attempts have been used up, the transfer is automatically rejected (the transfer is returned to the sender). Required token permissions: incoming-transfers. Input parameters Parameter Type Description operation_id string Identifier of the operation; the value of the operation_id parameter in the response to the operation-history method.

protection_code string Secret code.

String of four decimal digits. Specified for an incoming transfer protected by a secret code. Omitted for deferred transfers. Returns The method returns the following parameters: Parameter Type Description status string Operation result code (see the table). error string Operation processing error code (additional description for the status field). Present only for errors. protection_code_att empts_available int The remaining number of attempts to accept an incoming transfer that is protected by a secret code. Present only if the wrong secret code was entered.

ext_action_uri string The address to send the user to in order to complete necessary actions if the ext_action_required error occurs. Operation processing result codes: Code Description success The incoming transfer was accepted successfully. refused Refusal to perform the operation. If an error occurred while processing the transaction, the error code is returned: Code Description illegal_param_protection_co de Omitted or has an invalid value for the protection_code parameter. illegal_param_operation_id Omitted or has an invalid value for the operation_id parameter. A transfer with this operation_id does not exist or has already been refused.

ext_action_required Transfers cannot be accepted at this time. To be able to accept transfers, the user must go to the page with the ext_action_uri address and follow the instructions on that page. This may be any of the following actions: • entering identification data • accepting the offer • performing other actions according to the instructions on the page already_rejected The transfer was already rejected. Payments from the Yandex.Money wallet Yandex.Money API API for Apps 48

Examples Accepting an incoming transfer protected by a secret code: POST /api/incoming-transfer-accept HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 41 operation_id=1234567&protection_code=0123 Example response when successful: { "status":"success" } Example response if an invalid secret code was entered: { "status":"refused", "error":"illegal_param_protection_code", "protection_code_attempts_available":2 } incoming-transfer-reject method Description Canceling incoming transfers with a secret code and deferred transfers.

If the transfer is canceled, it is returned to the sender.

Required token permissions: incoming-transfers. Input parameters Parameter Type Description operation_id string Identifier of the operation; the value of the operation_id parameter in the response to the operation-history method. Returns The method returns the following parameters: Parameter Type Description status string Operation result code (see the table). error string Operation processing error code (additional description for the status field). Present only for errors. Operation processing result codes: Code Description success The incoming transfer was refused successfully. refused Refusal to perform the operation.

Payments from the Yandex.Money wallet Yandex.Money API API for Apps 49

If an error occurred while processing the transaction, the error code is returned: Code Description illegal_param_operation_id Omitted or has an invalid value for the operation_id parameter. A transfer with this operation_id does not exist or has already been refused. already_rejected The transfer was already rejected. Examples Request example: POST /api/incoming-transfer-reject HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLM NOPQRSTUVWXYZ 0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ012 3456789ABCDEF GHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHI JKLMNOPQRSTUV WXYZ0123 Content-Type: application/x-www-form-urlencoded Content-Length: 20 operation_id=1234567 Example response when successful: { "status":"success" } Example response if an invalid secret code was entered: { "status":"refused", "error":"illegal_param_operation_id" } Payments from the Yandex.Money wallet Yandex.Money API API for Apps 50

Payments from bank cards without authorization Payments from bank cards without authorization General information The API is intended for: • Payment of goods and services using any bank card without user authorization in Yandex.Money. • Saving information about bank cards for repeated payments without entering the complete card data. • Usage on users' personal devices and embedding in various mobile apps. The API allows you to: • Pay for goods and services in stores that are connected to Yandex.Money. • Deposit funds to users' Yandex.Money accounts. • Save information about one or more bank cards and use it for subsequent payments.

To get started: 1. Register your application and get a client_id (application identifier). 2. Activate Yandex.Checkout (for businesses or individual entrepeneurs) or create a Wallet in Yandex.Money (for individuals).

Usage scenarios Registering an instance of the application Before making the first payment, you need to register a copy of the application in Yandex.Money that is installed on a device and get an identifier for the instance of the application — instance_id. To register an instance, call the instance-id method. What you should know about the identifier: • It is only received once. • It is remembered in a secure location on the device (storing it on an SD card is not allowed; you should use KeyChain or SharedPreferences).

• It is passed as a parameter for all other functions. • It is deleted from the device when the application is deleted.

General payment scenario 1. Payments are processed based on the Payment Pattern with user parameters specified. Each merchant has its own set of these parameters, so the application must show the user a form requesting the information that is needed by a specific store. For example: the payment amount, phone number, contract number, and so on. 2. The application sends a payment request request-external-payment, which contains the Payment Pattern ID and the parameters entered by the user. The Yandex.Money server checks the payment parameters and returns the payment context ID (request_id).

3. If the user confirmed the payment, the application sends a request to make the payment (process- external-payment) that specifies the payment context ID (request_id). Payments from bank cards without authorization Yandex.Money API API for Apps 51

Note that the application may need a repeat call of the process-external-payment method. This method should be called until the payment process is complete. This may require additional user steps in WebView. Repeated calls are necessary if: • The bank card data must be entered on the Yandex.Money page in WebView.

• The user must go to the issuing bank's page to confirm the transaction over 3-D Secure. • Payment processing is not yet complete. • The internet connection was lost during the payment process. Rules for payment processing: 1. Money is debited from the bank card when the process-external-payment method is called. 2. If the process-external-payment call is repeated, the method returns the state of the previous payment.

3. If the internet connection is lost, the server times out, or other network errors occur, the application should repeat the call with the same parameters. First payment Payments from bank cards without authorization Yandex.Money API API for Apps 52

1. The application sends a payment request (request-external-payment), which contains the Payment Pattern ID and the user parameters. The Yandex.Money server checks the payment parameters and returns the payment context ID (request_id). 2. The application sends a request to make the payment (process-external-payment) that specifies the payment context ID (request_id).

The Yandex.Money server responds with a request to open WebView at the link (status=ext_auth_required, acs_uri, acs_params). 3. The application opens WebView and goes to the acs_uri address. After this: 1. The user enters the bank card data on the Yandex.Money page. 2. If necessary, the user authenticates using 3-D Secure technology on the issuing bank's page. 3. The user returns to ext_auth_success_uri (if the bank card data was accepted for processing), or ext_auth_fail_uri (if the card data was refused by the payment gateway). 4. The application repeats process-external-payment calls until it gets the final payment status (success/ refused).

5. The application shows the user the payment result and asks permission to save the bank card data. 6. If the user agrees to save the card data, the application re-sends the process-external-payment request with the request_token=true parameter. After this: 1. The Yandex.Money server returns the bank card data and a token for repeated payments. 2. The application saves the bank card data and the token for repeated payments in a secure location on the device. Bank card data and token for repeated payments: • Are remembered in a secure location on the device (storing it on an SD card is not allowed; KeyChain and SharedPreferences are allowed).

• Are deleted from the device when the application is deleted. Payment with saved bank card data This type of payment may require authentication using 3-D Secure technology, depending on the issuing bank's policy and information about the user's device or a specific transaction. Payments from bank cards without authorization Yandex.Money API API for Apps 53

Payment using saved bank card data without 3-D Secure authentication: 1. The application sends a payment request (request-external-payment), which contains the Payment Pattern ID and the user parameters.

The Yandex.Money server checks the payment parameters and returns the payment context ID (request_id). 2. The application repeats payment requests (process-external-payment), specifying the payment context identifier (request_id), the token for repeated payments and the bank card's CVV2/CVC2 code until it gets the final payment status.

Payment using saved bank card data with 3-D Secure authentication: 1. The application sends a payment request (request-external-payment), which contains the Payment Pattern ID and the user parameters. The Yandex.Money server checks the payment parameters and returns the payment context ID (request_id). 2. The application sends a payment requests (process-external-payment), specifying the payment context identifier (request_id), the token for repeated payments and the bank card's CVV2/CVC2 code. The Yandex.Money server responds with a request to open WebView at the link (status=ext_auth_required, acs_uri, acs_params).

3. The application opens WebView and goes to the acs_uri address. After this: 1. The user authenticates using 3-D Secure technology on the issuing bank's page. 2. The user returns to ext_auth_success_uri (if the transaction was accepted for processing) or ext_auth_fail_uri (if the transaction was refused). 4. The application repeats process-external-payment calls until it gets the final payment status (success/ refused). Payments from bank cards without authorization Yandex.Money API API for Apps 54

List of methods • instance-id • request-external-payment • process-external-payment instance-id method Description Registering an instance of the application.

Request parameters: Parameter Type Description client_id string Application ID. Returns Response fields: Parameter Type Description status string Operation result code (see the table). error string Error code (explanation of the "status" field). Present only for errors (see the table). instance_id string ID of the application instance. Operation processing result codes: Code Description success Success. refused Refusal. The reason for refusal is returned in the error field. If an error occurred while processing the transaction, the error code is returned: Code Description illegal_param_client_id Invalid value for the client_id parameter (non-existing or blocked).

The application cannot work with this client_id.

Examples Request example: POST /api/instance-id HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 75 client_id=1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1 Example of a response document when successful: {"status": "success", "instance_id": "1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1234567890ABCDEF1"} Example of a response document for an error: Payments from bank cards without authorization Yandex.Money API API for Apps 55

{"status": "refused", "error": "illegal_param_client_id"} See also Payments from bank cards without authorization request-external-payment method process-external-payment method request-external-payment method Description Creating a payment and checking its parameters.

Arguments for making a payment to a merchant The parameters for making a payment to a merchant are defined by the counterparty when connecting to Yandex.Checkout. Additional information about payment parameters is provided in the payment solution protocol for merchants and integration scenarios.

Parameter Type Description pattern_id string Payment Pattern ID. Corresponds to the merchant's scid (payment form number). instance_id string ID of the application instance. * string Payment Pattern parameters required by the merchant. Request parameters for making a deposit to a Yandex.Money user's Wallet: Parameter Type Description pattern_id string Constant value "p2p". instance_id string ID of the application instance. to string Account number to make the deposit to. amount amount Amount to deduct from the bank card (this amount minus the commission fee will be deposited to the account).

amount_due amount Amount to deposit to your account (this amount plus the commission fee will be debited from the card).

message string Comments on the deposit (displayed to the recipient). Note: Only one of the two fields may be set in the parameters: either amount, or amount_due. Note: After sending "request-payment", the user can be shown the commission for the payment. The response to the request will show the contract_amount. Use this formula to calculate the commission: Commission = contract_amount — amount_due Payments from bank cards without authorization Yandex.Money API API for Apps 56

The commission is rounded to the kopek (two decimal points). A commission that is less than one kopek is always rounded up to one kopek. Returns Response fields: Parameter Type Description status string Operation result code (see the table). error string Error code (explanation of the status field). Present only for errors (see the table). request_id string Payment context ID. Present only on success. contract_amount amount Amount to debit from the bank card, in rubles. Present only on success. title string Payment title.

Operation processing result codes: Code Description success Success.

refused Payment processing was refused. The reason for refusal is returned in the error field. Final state. If an error occurs, its code is returned: Code Description illegal_param_to Invalid value for the to parameter. illegal_param_amount Invalid value for the amount parameter. illegal_param_amount_due Invalid value for the amount_due parameter. illegal_param_message Invalid value for the message parameter. payee_not_found Recipient not found; the specified account does not exist. payment_refused The merchant refused to accept the payment (for example, the user tried to pay for an item that is not in stock).

illegal_params or any other value Required payment parameters are either missing, have invalid values, or logically contradict each other. Examples Example of a request to make a payment: POST /api/request-external-payment HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 130 pattern_id=99999&instance_id=1234567890ABCDEF1234567890ABCDEF1234 567890ABCDEF1234567890ABCDEF1&amount=100.00&merchantArticleId=123 Example of a request to make a deposit to an account: POST /api/request-external-payment HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 125 pattern_id=p2p&instance_id=1234567890ABCDEF1234567890ABCDEF123456 7890ABCDEF1234567890ABCDEF1&to=41001101140&amount_due=100.00 Example of a response document when successful: Payments from bank cards without authorization Yandex.Money API API for Apps 57

{ "status": "success", "request_id": "3931303833373438395f34343431646631386461623661 3236363063386361663834336137386537643935383639383062635f3330363 333323938", "contract_amount": 100.00, "title": "Оплата услуг NNNN" } Example of a response document for an error: {"status": "refused", "error": "illegal_params"} See also Payments from bank cards without authorization request-external-payment method process-external-payment method process-external-payment method Description Making a payment. The application calls the method up until the final payment status is known (status=success/ refused).

The recommended retry mode is determined by the "next_retry" response field (by default, 5 seconds).

Request parameters Request parameters for: • The first payment or deposit. • A repeated request after entering card data or authenticating using 3-D Secure. Parameter Type Description request_id string Payment context ID obtained from the request-external-payment method response. instance_id string ID of the application instance. ext_auth_success_ur i string Address of the page to return to when card payment has been successfully authenticated using 3-D Secure technology.

ext_auth_fail_uri string Address of the page to return to when card payment has failed 3-D Secure authentication. request_token boolean If this parameter is present and has the value "true", the application requests a token for repeat payments. By default, the parameter is omitted (a token for repeat payments is not requested). Parameters for a repeated payment request using a token: • Without entering card data. • With a repeated request after authentication via 3-D Secure. Parameter Type Description request_id string Payment context ID obtained from the request-external-payment method response.

instance_id string ID of the application instance. Payments from bank cards without authorization Yandex.Money API API for Apps 58

Parameter Type Description ext_auth_success_ur i string Address of the page to return to when card payment has been successfully authenticated using 3-D Secure technology. ext_auth_fail_uri string Address of the page to return to when card payment has failed 3-D Secure authentication. money_source_token string Token for repeated payments. csc string, 3 digits Card Security Code, CVV2/CVC2 code on the bank card. Returns Response fields: Parameter Type Description status string Operation result code (see the table).

error string Error code (explanation of the "status" field). Present only for errors (see the table).

acs_uri string Address of the 3-D secure bank card authentication page on the issuing bank's side. This field must be present if 3-D Secure authentication is required in order to complete a transaction using a bank card. acs_params object Authentication parameters for 3-D Secure technology in the form of a name-value collection. This field must be present if 3-D Secure authentication is required in order to complete a transaction using a bank card. money_source object Bank card data for repeated payments. This field is present if the request parameter request_token=true is set, the payment was completed successfully, and the server approved issuing a token for this operation.

Note: If the server refused to issue a token, this field is omitted in the response. next_retry long The recommended length of time (in milliseconds) before repeating the request. This field is present when status=in_progress invoice_id string The transaction number in Yandex.Money. Present when payment was successfully made to a merchant.

Operation processing result codes: Code Description success Payment processing completed successfully. refused Payment processing was refused. The reason for refusal is returned in the error field. Final state. in_progress Payment processing is not yet complete. The application should repeat the request with the same parameters after the amount of time in "next_retry" has passed. ext_auth_required Processing a bank card payment requires additional verification by the issuing bank (3-D Secure authentication). You should open WebView and use a POST request to send the client to the "acs_uri" address with the "acs_params" parameters.

If an error occurred while processing the transaction, the error code is returned: Code Description illegal_param_request_id Invalid value for request_id or missing context with the set request_id illegal_param_csc The csc parameter has a missing or invalid value.

illegal_param_instance_id The instance_id parameter has a missing or invalid value. illegal_param_money_source_ token The money_source_token parameter has a missing or invalid value, the token was revoked or expired. Payments from bank cards without authorization Yandex.Money API API for Apps 59

Code Description payment_refused The payment was refused. Possible reasons: • The merchant refused to accept the payment (checkOrder request). • The transfer to a Yandex.Money user is not possible (for example, the recipient's wallet has reached the maximum amount allowed).

authorization_reject Authorization of the payment was refused. Possible reasons: • The issuing bank refused to perform the transaction for the card. • A transaction with the current parameters is forbidden for this user. illegal_param_ext_auth_succ ess_uri The ext_auth_success_uri parameter has a missing or invalid value. illegal_param_ext_auth_fail _uri The ext_auth_fail_uri parameter has a missing or invalid value. Bank card data for repeated payments: Parameter Type Description type string Type of funding-source: payment-card — bank card. payment_card_type string The type of card; may be omitted if unknown.

Accepted values: Visa, MasterCard, AmericanExpress, JCB.

pan_fragment string Masked card number; the last four digits are visible. money_source_token string Generated token for repeated payments. Examples Example of a request to make a payment: POST /api/process-external-payment HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 305 request_id=3931303833373438395f34343431646631386461623661323636306338636166 38343 36137386537643935383639383062635f3330363333323938&instance_id=1234567890ABC DEF12 34567890ABCDEF1234567890ABCDEF1234567890ABCDEF1&ext_auth_success_ur=yandexm oney app%3A%2F%2Fsuccess&ext_auth_fail_uri=yandexmoneyapp%3A%2F%2Ffail Example of a request to get a token: POST /api/process-external-payment HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 324 request_id=3931303833373438395f34343431646631386461623661323636306338636166 38343 36137386537643935383639383062635f3330363333323938&instance_id=1234567890ABC DEF12 34567890ABCDEF1234567890ABCDEF1234567890ABCDEF1&ext_auth_success_uri=yandex money app%3A%2F%2Fsuccess&ext_auth_fail_uri=yandexmoneyapp%3A%2F%2Ffail&request_t oken= true Example of a payment request with a token: POST /api/process-external-payment HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 589 request_id=3931303833373438395f34343431646631386461623661323636306338636166 38343 36137386537643935383639383062635f3330363333323938&instance_id=1234567890ABC DEF12 34567890ABCDEF1234567890ABCDEF1234567890ABCDEF1&ext_auth_success_uri=yandex money app%3A%2F%2Fsuccess&ext_auth_fail_uri=yandexmoneyapp%3A%2F%2Ffail&money_sou rce_t oken=B6AE719BAF712404E08EF8A430B0F58CD8F2C592452CA5205F7E52B1FC72BD3D427457 14 D60B4E75BD742F22E8120F0861ED99B69EC01C6194CF5D425C89598B959DE0E9EDB13AFD710 CF 74ACE08DBFBE2A49F14F9792B32289CE2456EB50EF7DFE6D22E466D417ACD1BF8DE33B5C93B DA 9AAA8C4D693DCD2E9AA2A31A51C185&csc=123 Payments from bank cards without authorization Yandex.Money API API for Apps 60

Example of a response document for a successfully processed payment: {"status": "success", "invoice_id": "3000130505460"} Example of a response document when 3-D Secure authentication was requested for the card: { "status": "ext_auth_required", "acs_uri": "https://acs.alfabank.ru/acs/PAReq", "acs_params": { "MD": "723613-7431F11492F4F2D0", "PaReq": "eJxVUl1T2zAQ/CsZv8f6tCR7LmLSGiidJjAldMpTR7XVxA N2gmynSX59JeNAebu9O93u7QkuDvXzZG9dW22bWURiHE1sU2zLqlnPo ofV1VRFFxpWG2dtfm+L3lkNC9u2Zm0nVTmLVvn9r7v5d/uS/UkYt4b8 tjibUiGVxazICMeSSkmtwBmlhYw=" } } Example of a response document if payment processing has not yet been completed: {"status": "in_progress", "next_retry": "5000"} Example of a response document if the payment was rejected: {"status": "refused", "error": "payment_refused"} Example of a response document when a token was successfully issued for repeated payments: { "status": "success", "invoice_id": "3000130505460", "money_source": { "type": "payment-card", "payment_card_type": "VISA", "pan_fragment * 0334", "money_source_token": "B6AE719BAF712404E08EF8A430B0F58CD8 F2C592452CA5205F7E52B1FC72BD3D42745714D60B4E75BD742F22E8120F0861E D99B69EC01C6194CF5D425C89598B959DE0E9EDB13AFD710CF74ACE08DBFBE2A4 9F14F9792B32289CE2456EB50EF7DFE6D22E466D417ACD1BF8DE33B5C93BDA9AA A8C4D693DCD2E9AA2A31A51C185" } } Example of a response document when a token for repeated payments was not issued (refused): {"status": "success", "invoice_id": "3000130505460"} See also Payments from bank cards without authorization instance-id method request-external-payment method Payments from bank cards without authorization Yandex.Money API API for Apps 61

Notification of events Notification of incoming transfer Notification is sent if: • The user has a transfer from another Yandex.Money user. • The user has incoming funds from a bank card via the multipurpose form, donation form, or button. Attention! When receiving notifications, always check the status of the incoming transfer in the unaccepted and codepro fields. • If unaccepted=true, the transfer hasn't been credited to the user's account yet. In order to accept it, the user must complete additional steps. For example, to free up space on the account if the user's limit is reached. Or enter the secret code, if this is required for receiving the transfer.

• If codepro=true, the transfer is protected by a secret code. To receive a transfer like this, the user must enter the secret code. Request format The notification is sent as an HTTP request to the address specified in the account settings, in the following format: • POST method. • Key/value pairs for each notification parameter, packed as HTTP 1.1 POST request parameters. • MIME type: application/x-www-form-urlencoded. • UTF-8 encoding. Yandex.Money makes three attempts to deliver the notification: immediately when the transfer is received, ten minutes later, and one hour later.

We recommend using the HTTPS protocol to get notifications.

Note that you cannot get the sender's contact information in notifications unless you are using this protocol. When using the HTTP protocol, contact data is not passed in notifications. If the notifications do not arrive, check your settings: make sure the correct server address is indicated, and your server is currently available (you can use the "Test" button). The record of the incoming transfer is saved in the wallet history.

Notification of events Yandex.Money API API for Apps 62

Tip: We recommend using the HTTPS protocol to get notifications. Note that you cannot get the sender's contact information in notifications unless you are using this protocol. When using the HTTP protocol, contact data is not passed in notifications. Notification parameters HTTPS Parameter Type Description no notification_type string For transfers from a wallet — p2p-incoming. For transfers from another card — card-incoming. operation_id string Operation ID in the history of the account that is receiving the transfer.

amount amount Operation amount. withdraw_amount amount The amount of money withdrawn from the sender's account. currency string User's account currency code. Always 643 (ruble of the Russian Federation conforming to ISO 4217). datetime datetime Transfer timestamp (date and time). sender string For transfers from a wallet, this is the sender's account number. For transfers from any other card, the parameter contains an empty string. codepro boolean For transfers from a wallet, the transfer has a protection code. For transfers from any other card, it is always false.

label string Payment label.

If the payment does not have a label, the parameter contains an empty string. sha1_hash string SHA-1 hash of notification parameters. test_notification boolean This flag means this is a test notification. By default, omitted. unaccepted boolean This flag indicates that the user didn't receive the transfer. Possible reasons: • The payment was put on hold because the user's account reached the available remainder limit. It is displayed in the hold field in the response to the account-info method.

• The transfer is protected by a secret code. In this case, codepro=true. yes lastname firstname fathersname string string string Full name of the transfer's sender. If this information was not requested, these parameters contain an empty string. email string Email address of the transfer's sender. If the email address was not requested, this parameter contains an empty string. phone string Phone number of the transfer's sender. If the phone number was not requested, this parameter contains an empty string. city street building string string string The address specified by the sender for delivery.

If the address was not requested, these parameters contain an empty string.

Notification of events Yandex.Money API API for Apps 63

HTTPS Parameter Type Description suite flat zip string string string Response format A notification is considered delivered if the recipient responded to the request with an HTTP 200 OK code. Tip: To get the other payment parameters, including the “Payment comment”, call operation-details and specify the operation_id parameter that you received in the notification. Verifying notification authenticity and integrity One of the notification parameters, sha1_hash, contains the SHA-1 hash function value from packing notification parameters together with the secret word.

Note: The secret word for verifying notification is like a secret shared between Yandex.Money and the application developer. This means that notifications can't be faked. You can get the secret word in the account settings. Always check the value of the sha1hash parameter. This is necessary to: • Verify the integrity of the notification data. • Make sure that the notification was sent by Yandex.Money. To check the integrity and authenticity of the notification, calculate the hash using the algorithm below. Compare the data obtained with the value of the sha1_hash parameter in the notification.

1. Create a UTF-8 string from the notification parameters (where notification_secret is the secret word for verifying notifications).

String format: notification_type&operation_id&amount&currency&datetime&sender&codepro&noti fi cation_secret&label Example of a parameter string: p2p- incoming&1234567&300.00&643&2011-07-01T09:00:00.000+04:00&41001XXXXXXXX&fal se &01234567890ABCDEF01234567890& Example of a parameter string with a payment label: p2p- incoming&1234567&300.00&643&2011-07-01T09:00:00.000+04:00&41001XXXXXXXX&fal se &01234567890ABCDEF01234567890&YM.label.12345 2. Calculate the value of the SHA-1 hash function from the resulting string. 3. Format the resulting value in HEX encoding.

Example of the calculated value of the sha1_hash parameter for the last sample: a2ee4a9195f4a90e893cff4f62eeba0b662321f9 Notification of events Yandex.Money API API for Apps 64

Examples of parameters Notification of a transfer from a card requesting the sender's full name, address, phone, email, and transmitting the hidden label field over the HTTPS protocol: operation_id = 904035776918098009 notification_type = p2p-incoming datetime = 2014-04-28T16:31:28Z sha1_hash = 8693ddf402fe5dcc4c4744d466cabada2628148c sender = 41003188981230 codepro = false currency = 643 amount = 0.99 withdraw_amount = 1.00 label = YM.label.12345 lastname = Иванов firstname = Иван fathersname = Иванович zip = 125075 city = Москва street = Тверская building = 12 suite = 10 flat = 10 phone = +79253332211 email = adress@yandex.ru Example of the same notification when the HTTP protocol is used: operation_id = 904035776918098009 notification_type = p2p-incoming datetime = 2014-04-28T16:31:28Z sha1_hash = 8693ddf402fe5dcc4c4744d466cabada2628148c sender = 41003188981230 codepro = false currency = 643 amount = 0.99 withdraw_amount = 1.00 label = YM.label.12345 Notification of events Yandex.Money API API for Apps 65

Payment forms for purchasing products and services Payment forms for purchasing products and services The API is intended for working with payment forms. You can use it to: • Request descriptions of payment forms. • Verify data entered by a buyer. • Get parameters for calling payment functions (from a Yandex.Money wallet or with a bank card). For example, you can use this API to transfer money to any Russian company using the bill payment form: pattern-id=5551. Note: Payment forms in JSON format are not available for all products and services. Payment forms can be basic or multistep.

Multistep forms are for implementing dynamic user services, when the service's subsequent actions depend on the information entered by the buyer.

From the technical viewpoint, the API is a tool for working with documents on a remote server over the HTTP/ 1.1 (RFC-7231) protocol. The client behavior corresponds to browser behavior when working with internet resources. Client authorization is not required for accessing the API. The payment form description is available in various languages. Specify the desired language in the request. By default, the Russian description is loaded.

Payment form usage scenarios: 1. The form description is downloaded and shown to the buyer. 2. The buyer fills in the form. 3. The form is sent to the server for verification: 1. If the data entered by the buyer is valid, the server returns a set of payment parameters. 2. If errors are found, the server returns a list of errors and the payment form as filled in by the buyer. Descriptions of basic single-step forms can be cached on the client side. The description of the form fields contains rules for checking the values entered by the buyer. The client should check the contents of the form fields against these rules before sending the form data to the server.

Searching for business details Description This method is for searching for payment forms in Yandex.Money using details of the business or organization. Payment forms for purchasing products and services Yandex.Money API API for Apps 66

Request format GET /api/showcase-search?query=&records= HTTP/1.1 Host: money.yandex.ru Accept-Language: Request URL parameters: Parameter Type Description query string The search query, word or phrase. records int Maximum number of records in the method output. The request may contain the following HTTP headers: Header Description Accept-Language The code of the language that the client wants to get the form description in, conforming to RFC-5646: Tags for Identifying Languages IANA Language Subtag Registry Possible values: • ru — Russian • en — English By default: Russian. Returns Parameter Type Description error string Error code.

Passed if an error occurred when executing the request.

result array List of results. nextPage boolean A predicate that determines whether there are records over the requested limit. The result element contains: Parameter Type Description id int The payment form ID (pattern_id). title string Name of the recipient. url string Address for sending payment form data. params object Set of pre-filled fields from the first step of the payment form. format string Format of the payment form. Possible values: • json May be omitted. The form description can be requested only when format is set to "json". Payment forms for purchasing products and services Yandex.Money API API for Apps 67

Operation processing error codes: Code Description illegal_param_query Invalid value for the query parameter: • Parameter omitted. • Contains an empty string. • Contains an invalid value. illegal_param_records Invalid value for the records parameter: • Parameter omitted. • Contains a non-number. • Contains an invalid value (for example, -1). Example Querying details for the string "PetroElectric": GET /api/showcase-search?query=PetroElectric&records=3 HTTP/1.1 Host: money.yandex.ru Accept: */* Response: HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Content-Length: 454 {"result":[{"id":5670,"title":"PetroElectric"},{"id": 5551,"title":"PETROELECTRIC, INC","url":"https://money.yandex.ru/api/showcase/ validate/5551/step_INN_3038","params":{"supplierInn , " format":"json"},{"id": 5551,"title":"PetroElectric, Inc","url":"https://money.yandex.ru/api/showcase/ validate/5551/step_INN_3038","params": {"supplierInn":"7812013775"},"format":"json"}],"nextPage":"false"} Form description request Description To request the form description, send a GET request to the address: https://money.yandex.ru/api/showcase/ The request is equivalent to downloading a document from a remote server.

We recommend client-side caching for the description of simple forms, since these form descriptions rarely change.

Do not cache subsequent steps in multistep forms, since their state depends on the data entered by the buyer at the first step. Request format GET /api/showcase/ HTTP/1.1 Host: money.yandex.ru Accept-Language: Accept-Encoding: If-Modified-Since: Payment forms for purchasing products and services Yandex.Money API API for Apps 68

Request URL parameters: Attribute Type Description pattern_id string Payment Pattern ID. The request may contain the following HTTP headers: Header Description Accept-Language The code of the language that the client wants to get the form description in, conforming to RFC-5646: Tags for Identifying Languages IANA Language Subtag Registry Possible values: • ru — Russian • en — English By default: Russian.

Accept-Encoding Indicates client support for traffic compression. Supported values: • gzip — Support for GZIP transfer encoding (RFC-1952: GZIP file format specification).

By default: file compression is not used. If-Modified-Since If the payment form description was stored in the client's cache, it indicates the Last- Modified value for the server's response to the previous request. If the client does not cache form descriptions, the header is omitted. The method returns one of the following responses: • The payment form description. • Indication that the form does not exist. • Indication that a different form should be used. • Indication that the form has not changed since the previous request. Possible HTTP response codes: HTTP response code Description 300 Multiple Choices Success.

The response contains the payment form description. The address for sending the form to is given in the HTTP Location header.

301 Moved Permanently A different form should be used instead of the requested payment form. The address of the new form is given in the HTTP Location header. The response body is omitted. 304 Not Modified The payment form description has not changed since the previous request. The response body is omitted. 404 File Not Found The requested payment form does not exist or is not allowed to be used. The response body is omitted. 500 Internal Server Error The service is temporarily unavailable for technical reasons. The server response contains the following special HTTP headers: HTTP response code Description Location The address for sending form data to the server.

Alternatively, it is the new address of the form, if a different form should be used.

Content-Encoding gzip, if the client requested traffic compression. Payment forms for purchasing products and services Yandex.Money API API for Apps 69

HTTP response code Description Cache-Control Indicates the client-side caching mode. Possible values: • private — The payment form description should be stored on the client side. • no-cache — The payment form description must not be cached. Last-Modified Date and time of the latest changes to the form description. For clarity, some of the examples below are shown as formatted, without compression. The server returns JSON- compact as a compressed format.

Example Example: Returned description of a simple form or the first step of a multistep form. HTTP/1.1 300 Multiple Choices Location: https://money.yandex.ru/api/showcase/ 5551 Content-Type: application/json Content-Length: 539 Cache-Control: private Last-Modified: Thu, 17 Jul 2014 09:00:25 GMT {"money_source":["wallet","cards","payment- card","cash"],"title":"Bills","hidden_fields": {"ShopID":"13423","ShopArticleID":"35241","ShowCaseID":"3005","ContractTemp lat eID":"524867","budgetDocNumber":"0","has_external_status , " is_withdrawal":" "},"form":[{"type":"text","name":"supplierInn","hint":"10 digits (12 digits for sole proprietors)","label":"Recipient INN:","alert":"Please enter the recipient's INN","required":true,"readonly":false,"minlength":10,"maxlength": 12,"pattern \ \ d{10 \ \ d{12 { " type":"submit","label":"Continue"}]} Example: Redirection to a new form.

HTTP/1.1 301 Moved Permanently Location: https://money.yanex.ru/api/showcase/5551 Example: The payment form does not exist or is not allowed to be used. HTTP/1.1 301 Moved Permanently Location: https://money.yanex.ru/api/showcase/5551 Example: The payment form does not exist or is not allowed to be used. HTTP/1.1 404 Not Found Content-Length: 0 Sending a form or step of a form to the server Request format The address for submitting the form is in the Location header of the response to the request for the form description, or the response to sending form data for the previous step of a multistep form.

Note: The client must always take the address for sending the form from the server response, and never store it for later use.

Data should be submitted using the POST method, Сontent-Type: application/x-www-form-urlencoded, with UTF-8 encoding. Payment forms for purchasing products and services Yandex.Money API API for Apps 70

The request must contain the following parameters: • The content of all visible UI controls on the form. • The content of the hidden_fields section, if it exists in the form description. Note: If a UI control on the form is visible, optional, and the buyer left it empty, the name of the control's field and an empty value are added to the request. Web browsers behave the same way.

The request may contain the following HTTP headers: Header Description Accept-Language The code of the language that the client wants to get the form description in, conforming to RFC-5646: Tags for Identifying Languages IANA Language Subtag Registry Possible values: • ru — Russian • en — English By default: Russian. Accept-Encoding Indicates client support for traffic compression. Supported values: • gzip — Support for GZIP transfer encoding (RFC-1952: GZIP file format specification).

By default: file compression is not used. The method returns one of the following responses: • An indication that form data was verified successfully, along with payment parameters — this is the final state of the form. • An indication that form data was verified successfully, along with a description of the next step of the form. • A list of errors from checking data entered by the buyer, and a description of the current step of the form. Note: The response to this method must not be cached, since its contents depend on the data entered by the buyer. Possible HTTP response codes: HTTP response code Description 200 OK The information entered by the buyer was verified successfully.

This is the last step of the form. The response contains a list of parameters for processing the payment. 300 Multiple Choices The information entered by the buyer was verified successfully, and there is another step for the form. The response contains the description of the next step of the payment form. The address for sending the next step of the form is given in the HTTP Location header. 400 Bad Request The client specified invalid data in the form fields. The response contains a list of errors in the form data verification, along with the description of the current step of the form with pre-filled values entered by the buyer.

The address for re-sending the form is given in the HTTP Location header. The client must correct the form data and re-send it. 404 Not Found The requested payment form does not exist or is not allowed to be used. The response body is omitted.

500 Internal Server Error The service is temporarily unavailable for technical reasons. Payment forms for purchasing products and services Yandex.Money API API for Apps 71

List of parameters for processing payment The list of payment processing parameters is a collection of name-value pairs. This set should be passed as arguments for the payment function call (from a Yandex.Money wallet, or using a bank card). Response format with a list of parameters for payment processing { "params": { "param1": "value1", "param2": "value2", ... "paramN": "valueN" } } List of errors from verifying data entered by the buyer The server checks all the form field values and their logical combinations.

If errors are found, the server responds with: • A description of the current step of the form with pre-filled values entered by the buyer. • A list of errors in the error section.

Each item in the list of errors contains: Field Description name The name of the field containing an invalid value. If the error cannot be related to a specific field in the form, this parameter is omitted. alert The error message text. Format of a response with a list of errors verifying data entered by the buyer: { ... description of the current step in the form ... "form": [ ... ], "error": [ { "name": "field1", "alert": "Error message" }, ... { "name": "fieldN", "alert": "Error message" } ... { "alert": "Error message that isn't related to a specific field" } ] } Payment forms for purchasing products and services Yandex.Money API API for Apps 72

Examples Request example POST /api/showcase/validate/5551/step_INN_3038 HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 115 Accept-Language: ru Accept-Encoding: gzip supplierInn=4704020508&ShopID=13423&ShopArticleID=35241&ShowCaseID=3005&Con tra ctTemplateID=524867&budgetDocNumber=0 The data entered by the buyer was verified successfully and payment parameters were returned HTTP/1.1 200 ОК Content-Type: application/json Content-Length: 197 Cache-Control: no-cache {"params": {"pattern_id":"5506","ContractTemplateID":"525923","sc_param_scid":"5506"," net Sum":"2","ShopArticleID":"71747","sc_param_step , " ShopID":"14061","ShowCase ID":"6101","skypename":"test"}} The data entered by the buyer contains errors, and the returned document contains the reason for the error HTTP/1.1 400 Bad Request Location: https://money.yandex.ru/api/showcase/validate/5506/ Content-Type: application/json Content-Length: 733 Cache-Control: no- cache {"title":"Skype","form":[{"type":"group","layout":"VBox","items": [{"type":"text","name":"FormComment","value":"Skype","label":"Name","requir ed" :false,"readonly":false},{"type":"text","name":"skypename","label":"Skype login","required":true,"readonly":false}, {"type":"amount","name":"netSum","value":"2","label":"Amount","required":tr ue, "readonly":false,"min":0.01,"max":375,"currency":"EUR"}]}, {"type":"submit","label":"Pay"}],"money_source":["wallet","cards","payment- card","cash"],"hidden_fields": {"ContractTemplateID":"525923","sc_param_scid":"5506","netSum":"2","ShopArt icl eID":"71747","sc_param_step , " ShopID":"14061","ShowCaseID":"6101"},"error": [{"name":"skypename","alert":"Please enter the Skype login name"}]} Request for a form description with pre-filled field values Request format The request is for re-displaying the payment form to the user with the field values already filled in, to make it easier to repeat previously completed operations.

To request a form description with pre-filled fields, use the POST method at the same address as for requesting the payment form description: Address of the method: https://money.yandex.ru/api/showcase/ Сontent-Type: application/x-www-form-urlencoded, UTF-8 encoded. The request must contain a list of form field values, in the name-value format. Payment forms for purchasing products and services Yandex.Money API API for Apps 73

Note: The response to this method must not be cached, since its contents depend on the request arguments. Header Description Accept-Language The code of the language that the client wants to get the form description in, conforming to RFC-5646: Tags for Identifying Languages IANA Language Subtag Registry Possible values: • ru — Russian • en — English By default: Russian.

Accept-Encoding Indicates client support for traffic compression. Supported values: • gzip — Support for GZIP transfer encoding (RFC-1952: GZIP file format specification).

By default: file compression is not used. The method response is similar to the response to the request for the payment form description. The form fields are pre-filled with values from the request parameters. Request example POST /api/showcase/5506 HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 28 Accept-Language: ru Accept-Encoding: gzip skypename=username&netSum=10 Form description The description of the payment form is a JSON document in UTF-8 encoding. Example of the first step of the bill payment form { "title": "Bill", "form": [ { "type": "text", "name": "supplierInn", "hint": "10 digits (12 digits for sole proprietors)", "label": "recipient's INN", "alert": "Please specify the recipient's INN", "required": true, "readonly": false, "minlength": 10, "maxlength": 12, "pattern \ \ d{10 \ \ d{12}$" }, { "type": "submit", "label": "Continue" } ], Payment forms for purchasing products and services Yandex.Money API API for Apps 74

"money_source": [ "wallet", "cards", "payment-card", "cash" ], "hidden_fields": { "ShopID": "13423", "ShopArticleID": "35241", "ShowCaseID": "3005", "ContractTemplateID": "524867", "budgetDocNumber": "0", "has_external_status " , "is_withdrawal": "" } } Example of adding credit to a Skype account { "title": "Skype", "form": [ { "type": "text", "name": "FormComment", "value": "Skype", "label": "Name", "required": false, "readonly": false }, { "type": "text", "name": "skypename", "label": "Skype username", "required": true, "readonly": false }, { "type": "amount", "name": "netSum", "value": "0.00", "label": "Amount", "required": true, "readonly": false, "max": 375, "currency": "EUR" }, { "type": "submit", "label": "Pay" } ], "money_source": [ "wallet", "cards", "payment-card", "cash" ], "hidden_fields": { "ContractTemplateID": "525923", "ShopID": "14061", "ShopArticleID": "71747", "ShowCaseID": "6101" } } Payment forms for purchasing products and services Yandex.Money API API for Apps 75

Title fields on the form The title section The name of the product being purchased. Field type: string. Example "title": "RusTel Northwest" The hidden_fields section Service fields for the form. Field type: object, a key-value set. The client should transparently transmit the set of fields when the form data is sent to the server. Example "hidden_fields": { "targetcurrency": "643", "ShopArticleID": "35241" } The money_source section List of available payment methods. Field type: array. Payment method Description wallet Payment from a Yandex.Money wallet. cards Payment using bank cards that are linked to the account.

payment-card Payment using a bank card.

cash Payment in cash. Example "money_source": [ "wallet", "cards", "payment-card", "cash" ] The form section The description of the form that should be shown to the buyer. The form element is the root container for the form. It contains a list (group) of UI controls and containers. The client should render the elements inside form vertically, top to bottom. Example "form": [ ... UI controls and containers ... ] UI controls A UI control is a field on the form designed for the user to enter something. By default, all the control values must be filled in by the buyer, unless a form is explicitly declared to be optional (required=false).

The type of field data and rules for checking the values on the client side are determined by the control's type and attributes. Payment forms for purchasing products and services Yandex.Money API API for Apps 76

All the control attributes listed below always exist in a description, unless explicitly specified otherwise. General attributes of controls Attribute Type Description type string Type of UI control. Required attribute. name string Name of the form field, or parameter name for the form data submission request. Required attribute. value string Pre-set value of a control (other than checkbox).

Optional attribute. Omitted by default. value_autofill string Autofill macro for pre-setting field values by the client. Optional attribute. Omitted by default. If the client handles macros, their values determine the "value" attribute. hint string Hint for the buyer about the purpose and format of data in the field. Optional attribute. Omitted by default. label string Title of the field to display to the buyer as a label on the control. Optional field. Omitted by default.

alert string Error text to show to the buyer when there is an error verifying the information entered in this field. Optional field. Omitted by default. The text is for displaying when there is an error checking data on the client side. required boolean Indicates whether the field must be filled in by the buyer. By default, true. readonly boolean Indicates whether the field value can be changed. By default, false. text — Text box Single line for entering text. http://www.w3.org/TR/html5/forms.html#text-(type=text)-state-and-search-sta te-(type=search) Control-specific attributes: Attribute Data type Description type string Constant value: text.

minlength int Minimum allowed length of the string. Optional parameter, no default.

maxlength int Maximum allowed length of the string. Optional parameter, not restricted by default. pattern string Regular expression for checking values entered by the buyer. Regular expression format: ECMA-262 RegExp (JavaScript RegExp). Optional parameter. Omitted by default. keyboard_suggest enum Recommended type of on-screen keyboard for mobile devices. Payment forms for purchasing products and services Yandex.Money API API for Apps 77

Attribute Data type Description Possible values: • number — Display a digital keyboard for the field. By default, the attribute is not defined, and a text keyboard is displayed.

Example { "type": "text", "name": "surname", "label": "Last name", "required": true, "readonly": false } Example for a field with a set of decimal digits { "type": "text", "name": "kbk", "label": "KBK", "pattern": "[0-9]{20}", "required": true, "readonly": false, "keyboard_suggest": "number" } number — Number entry field Example for a field with a set of decimal digits http://www.w3.org/TR/html5/forms.html#number-state-(type=number) Control-specific attributes: Attribute Data type Description type string Constant value: number. min decimal number Minimum value. Optional attribute, no default (no minimum).

max decimal number Maximum value. Optional attribute, no default (no minimum). step decimal number Minimum number gradation ("step scale factor"). Optional attribute. Default value is 1. Payment forms for purchasing products and services Yandex.Money API API for Apps 78

Attribute Data type Description Examples of possible values: • 1 — Allows only integers. • 0.01 — Minimum allowed step of a decimal number. • 10 — Allows only integers that are multiples of 10. Example { "type": "number", "name": "qty", "label": "Amount, units", "step": 1, "required": true, "readonly": false } Example { "type": "number", "name": "coins", "label": "Amount in game currency", "step": 0.01, "required": true, "readonly": false } amount — Box for entering amount Single-line amount input field that extends the number type.

Control-specific attributes: Attribute Data type Description type string Constant value: amount. min decimal number Minimum value. By default, 0.01. max decimal number Maximum value. Optional attribute, no default (no minimum).

step decimal number Multiplication factor of the amount. By default, 0.01. currency string, \[A-Z\]{3} Three-letter currency code conforming to the ISO-4217 standard. By default, RUB. fee object Information about the commission charged to the buyer. If this section is included, it means that the buyer is charged a fee. By default, there is no fee charged to the buyer. Payment forms for purchasing products and services Yandex.Money API API for Apps 79

Attributes of the fee section: Attribute Data type Description type enum Type of fee charged to the buyer.

Can have the values: • std — The fee is based on a standard formula. • custom — The fee has a complex formula or is calculated by the merchant. The fee will be calculated during payment. You must inform the buyer that there is a fee. By default, std. a decimal number A coefficient of the amount to transfer to the merchant (netAmount). By default, 0. b decimal number A fixed fee per transaction, in currency units. By default, 0. c decimal number The minimum fee per transaction, in currency units. By default, 0.

d decimal number The maximum fee per transaction, in currency units. By default, 0. amount_type enum The type of amount on the payment form. Possible values: • amount — The amount to deduct from the buyer's account. • netAmount — The amount to transfer to the merchant (to be received). Payment forms for purchasing products and services Yandex.Money API API for Apps 80

Attribute Data type Description By default, amount. Example: 2% commission over the amount to transfer to the merchant { "type": "amount", "name": "sum", "label": "Amount", "min": 0.01, "step": 0.01, "currency": "RUB", "fee": { "a": 0.02, "amount_type": "netAmount" }, "required": true, "readonly": false } Example: A commission is calculated on the partner side during payment { "type": "amount", "name": "sum", "label": "Amount", "min": 0.01, "step": 0.01, "currency": "RUB", "fee": { "type": "custom" }, "required": true, "readonly": false } Information about commissions The payment form can have a commission fee set to charge the buyer.

The fee is defined by the formula: amount = netAmount + fee Where: • amount — The amount to deduct from the buyer's account. • netAmount — The amount to transfer to the merchant (to be received). • fee — The size of the fee charged to the buyer. Standard formula for calculating the commission fee fee = min(max(a * netAmount + b, c), d) Calculating "amount" from "netAmount" amount = netAmount + min(max(a * netAmount + b, c), d) Calculating "netAmount" from "amount" netAmount = amount - min(max(max(amount * (a / (1 + a)) + b / (1 + a), b), c), d) Minimum commission fee rule If there is a commission fee charged to the user, regardless of the rates in the formula, the commission must not be less than 0.01 of the currency unit for the account (1 kopek).

Payment forms for purchasing products and services Yandex.Money API API for Apps 81

If calculating the fee results in an amount less than 0.01, it is always rounded up to 0.01. Minimum amount rule When calculating netAmount from amount, you can only specify an amount for which netAmount will be greater than or equal to 0.01 units of the account currency (1 kopek). If a smaller amount is specified, this leads to an error — the payment is not possible. Standard types of commissions: Type Coefficients Without commission a=0, b=0, c=0, d=. The fee block is omitted. Percent of amount a=, b=0, c=0, d=.

Fixed commission fee per transaction a=0, b=, с=0, d=. Percent of amount AND fixed commission fee per transaction a=, b=, c=0, d=.

Percent of amount OR minimum commission fee per transaction a=, b=0, c=, d=. email — Email input field Box for entering an email address. http://www.w3.org/TR/html5/forms.html#e-mail-state-(type=email) Control-specific attributes: Attribute Data type Description type string Constant value: email. Example { "type": "email", "name": "email", "label": "Email", "required": true, "readonly": false } tel — Phone number input field Box for entering a phone number. http://www.w3.org/TR/html5/forms.html#telephone-state-(type=tel) The format of the phone number value sent to the server is ITU-T T.164, the complete phone number without a + sign.

For example, 79999999999.

The client can display the control as necessary, and choose the format for user input. Payment forms for purchasing products and services Yandex.Money API API for Apps 82

Control-specific attributes: Attribute Data type Description type string Constant value: tel. Example { "type": "tel", "name": "phone", "value": "79210000000", "hint": "International format", "label": "Phone number", "alert": "The phone number can only contain numbers", "required": true, "readonly": false } checkbox — Checkbox option A checkbox is a control that implements a true/false flag.

http://www.w3.org/TR/html5/forms.html#checkbox-state-(type=checkbox) The behavior of the control is defined in the HTML5 specification: • The value attribute defines the value that will be sent to the server if the option is selected. It can have any string value.

• The state of the control is defined by the checked attribute — whether the option is selected or deselected. • Only those fields that have the option selected (checked=true) are sent to the server. Control-specific attributes: Attribute Data type Description type string Constant value: checkbox. value string The value that will be sent to the server if the flag is set. checked boolean Starting state of the control: • true — Flag is set (checked). • false — Flag is cleared (unchecked).

Optional attribute. By default, false. Payment forms for purchasing products and services Yandex.Money API API for Apps 83

Attribute Data type Description required boolean • true — The form can be sent to the server only if the user selected the option. • false — The form can be sent to the server regardless of the state of the option (selected or unselected). Example { "type": "checkbox", "name": "notify_me", "value": "agreed", "checked" : true, "label": "Notify me of deposits", "readonly": false, "required": false } date — Date selection (day/month/year) A calendar for selecting the full date. http://www.w3.org/TR/html5/forms.html#date-state-(type=date) Control-specific attributes: Attribute Data type Description type string Constant value: date.

min date string or period Minimum date allowed. Optional attribute. By default, any date.

max date string or period Maximum date allowed. Optional attribute. By default, any date. When sending form data to the server, the field value must be in date string format, such as "2015-02-12". Example { "type": "date", "name": "receipt_date", "label": "Resolution date", "required": true, "readonly": false } month — Selection of month and year A calendar for selecting only the month and year http://www.w3.org/TR/2012/CR-html5-20121217/forms.html#month-state-(type=mo nth) Control-specific attributes: Attribute Data type Description type string Constant value: month. min month string or period Minimum allowed month and year.

Optional attribute. By default, any date.

max month string or period Maximum allowed month and year. Optional attribute. By default, any date. Payment forms for purchasing products and services Yandex.Money API API for Apps 84

When sending form data to the server, the field value must be in month string format, such as "2015-02". Example { "type": "month", "name": "period", "label": "Payment period", "required": true, "readonly": false } select — Selection of list item A control for selecting one of the values from a list. Only represents the data model. The visual display of the control is up to the client's discretion (ComboBox, Select, RadioGroup, Spinner, and so on).

http://www.w3.org/TR/html5/forms.html#the-select-element The control can change the visual state of the form by switching the form viewstates. Control-specific attributes: Attribute Data type Description type string Constant value: select. value string The selected default value. Optional field.

If this attribute is omitted or set to a null value, it means "nothing was selected". options array of object List of values to select from. style enum Control display recommended to the client. Optional attribute. By default, the client decides how to display this control. Possible values: • RadioGroup — RadioButton/ RadioGroup. • Spinner — Drop-down menus (ComboBox, DropDownList, Select). Attributes of list items: Attribute Data type Description value string The selected value that will be sent to the server as the value for this form field.

Required attribute. Its value must not be empty.

label string The text shown to the buyer in the list of values. group array of object A list (group) of UI controls and/or containers that become visible if this value is selected. May contain other nested select parameters. Payment forms for purchasing products and services Yandex.Money API API for Apps 85

Attribute Data type Description Optional attribute. By default, not defined (the form's visual state does not change). Example { "type": "select", "name": "country", "value": "gb", "label": "Country for calls", "options": [ { "value": "gb", "label": "Great Britain" }, { "value": "de", "label": "Germany" }, { "value": "es", "label": "Spain" }, { "value": "it", "label": "Italy" } ], "required": true, "readonly": false } Example: Selection changes the form's visible state { "type": "select", "name": "DeliveryType", "value": "ym_msk", "label": "Where to get the reader", "options": [ { "value": "ym_msk", "label": "at the Yandex.Money office in Moscow" }, { "value": "russianPost", "label": "at a Russian Post branch office (after delivery)", "group": [ // a group of UI controls and/or containers that becomes active if // this value is selected (a list of fields for entering the mailing address) ] } ], "required": true, "readonly": false } textarea — Multi-line text box A field for entering any text, which may consist of multiple lines.

http://www.w3.org/TR/html5/forms.html#the-textarea-element Payment forms for purchasing products and services Yandex.Money API API for Apps 86

Control-specific attributes: Attribute Data type Description type string Constant value: textarea. maxlength int Maximum allowed length of text, in characters. Optional attribute, not restricted by default. minlength int Minimum allowed length of text, in characters. Optional attribute, not defined by default. Example { "type": "textarea", "name": "comment", "label": "Comments on the transfer", "hint": "You can enter a message for the recipient here", "maxlength": 150, "required": false, "readonly": false } submit — Form submission button Button on the form that initiates sending it to the server.

http://www.w3.org/TR/html5/forms.html#submit-button-state-(type=submit) Control-specific attributes: Attribute Data type Description type string Constant value: submit. Example { "type": "submit", "label": "Pay", "required": true, "readonly": false } UI containers A container is a group of UI controls or static data to display to the buyer. General attributes of containers Attribute Type Description type string Type of container. Required attribute. group — Group of controls or containers A group containing a list of UI controls and/or nested containers All attributes are required, unless explicitly specified otherwise.

Container-specific attributes: Attribute Data type Description type string Constant value: group. items array List of controls and/or nested containers.

label string Group title (label on the group). Optional attribute. Omitted by default. Payment forms for purchasing products and services Yandex.Money API API for Apps 87

Attribute Data type Description layout enum Recommended layout of items inside the group. Possible values: • VBox — Vertically, top to bottom. • HBox — Horizontally, left to right. Optional attribute. By default: VBox. Example { "type": "group", "label": "Transfer recipient", "layout": "VBox", "items": [ { "type": "text", "name": "surname", "label": "Last name", "required": true, "readonly": false, "maxlength": 50, "alert": "Please enter the recipient's last name" }, { "type": "text", "name": "name", "label": "Name", "required": true, "readonly": false, "maxlength": 50, "alert": "Please enter the recipient's first name" }, { "type": "text", "name": "patronymic", "label": "Patronymic", "required": true, "readonly": false, "maxlength": 50, "alert": "Please enter the recipient's patronymic" } ] } p — Text paragraph A section of static text that may contain hyperlinks.

http://www.w3.org/TR/html5/dom.html#paragraphs Container-specific attributes: Attribute Data type Description type string Constant value: p. items Array List of paragraph elements. label string Paragraph title (label over the text section). Optional attribute.

Payment forms for purchasing products and services Yandex.Money API API for Apps 88

Paragraph elements can be: • text string (string type) • hyperlinks (object type) Hyperlink attributes: Attribute Data type Description type string Constant value: a. href URL HTTP(S) hyperlink. label string Hyperlink text displayed to the buyer. Example { "type": "p", "items": [ "By clicking \"Pay\", you are agreeing to the", { "type": "a", "href": "http://money.yandex.ru/doc/12345567890", "label": "terms of purchase of" }, "iTunes PIN code." ] } ViewState — Changeable form states You can change the set of visible form elements, depending on the values selected for specific controls with the select type.

Rules for working with forms with changeable states: • A form can be either single-step, or a step in a multistep form. • The description of a form or step of a form contains a complete list of UI controls and containers. • Each UI control or container has a visibility state: whether it is displayed on the form, or not. • ViewState (the form state) is a list of controls or containers displayed on the form in the current state. • One of the UI controls on the form switches the states.

The state switch logic works like the switch-case operator in popular programming languages: select { option X => elements visible in state X option Y => elements visible in state Y option Z => ....

} The UI controls and containers that are located inside a particular select option become visible only when the value for this option is selected. Payment forms for purchasing products and services Yandex.Money API API for Apps 89

When submitting form data to the server, only the values of the UI controls that are visible in this state are added to the request. Example: Payment form for purchasing an mPOS reader { "title": "Mobile terminal reader (mPOS)", "hidden_fields": { "rnd": "77122820", "scid": "6953", "shn": "Mobile terminal reader (mPOS)", "targetcurrency": "643", "SuccessTemplate": "ym2xmlsuccess", "ErrorTemplate": "ym2xmlerror", "ShowCaseID": "7", "isViaWeb": "true", "try-payment": "true", "FormComment": "Mobile terminal reader (mPOS)" }, "form": [ { "type": "text", "name": "Ewallet", "label": "Account number", "hint": "Money will be credited to this account", "value_aurofill": "currentuser_accountkey", "pattern": "[0-9]{11,33}", "required": true, "readonly": false }, { "type": "tel", "name": "contactPhoneNumber", "label": "Phone number", "required": true, "readonly": false }, { "type": "text", "name": "LastName", "label": "Last name", "maxlength": 150, "required": true, "readonly": false }, { "type": "text", "name": "FirstName", "label": "First name", "maxlength": 150, "required": true, "readonly": false }, { "type": "text", "name": "MiddleName", "label": "Patronymic", "maxlength": 150, "required": true, "readonly": false }, { "type": "select", "name": "DeliveryType", "value": "ym_msk", "label": "Where to get the reader", "options": [ { "value": "ym_msk", "label": "at the Yandex.Money office in Moscow" Payment forms for purchasing products and services Yandex.Money API API for Apps 90

}, { "value": "ym_spb", "label": "at the Yandex.Money office in St. Petersburg" }, { "value": "russianPost", "label": "at a Russian Post branch office (after delivery)", "group": [ { "type": "select", "name": "country", "value": "Russia", "label": "Country", "options": [ { "value": "Russia", "label": "Russia" }, { "value": "Belarusia", "label": "Belarusia" }, { "value": "Ukraine", "label": "Ukraine" }, { "value": "Moldova", "label": "Moldova" }, { "value": "Armenia", "label": "Armenia" }, { "value": "Azerbaijan", "label": "Azerbaijan" }, { "value": "Kyrgyzstan", "label": "Kyrgyzstan" }, { "value": "Kazakhstan", "label": "Kazakhstan" }, { "value": "Tajikistan", "label": "Tajikistan" }, { "value": "Turkmenistan", "label": "Turkmenistan" }, { "value": "Uzbekistan", "label": "Uzbekistan" } ] }, { "type": "text", "name": "index_address", "label": "Postal index", "pattern": "[0-9]{6,8}", "required": true, "readonly": false }, Payment forms for purchasing products and services Yandex.Money API API for Apps 91

{ "type": "text", "name": "deliveryRegion", "label": "Region", "maxlength": 44, "required": true, "readonly": false }, { "type": "text", "name": "address_1", "label": "City", "maxlength": 150, "required": true, "readonly": false }, { "type": "text", "name": "deliveryStreet", "label": "Street", "maxlength": 44, "required": true, "readonly": false }, { "type": "text", "name": "deliveryHouse", "label": "House number", "maxlength": 9, "required": true, "readonly": false }, { "type": "text", "name": "deliveryCorpus", "label": "Unit", "maxlength": 9, "required": true, "readonly": false }, { "type": "text", "name": "deliveryBuilding", "label": "Bldg.", "maxlength": 9, "required": true, "readonly": false }, { "type": "text", "name": "deliveryFlat", "label": "Apt.", "maxlength": 9, "required": true, "readonly": false } ], "required": true, "readonly": false } ] }, { "type": "p", "items": [ "By clicking this button, I accept", { "type": "a", "href": "http://money.yandex.ru/doc.xml?id=526489", Payment forms for purchasing products and services Yandex.Money API API for Apps 92

"label": "the terms of use for the mobile terminal" }, "." ] }, { "type": "submit", "label": "Continue", "required": true, "readonly": false } ] } Autofill macros Autofill macros are for pre-filling form fields with specific values on the client side. If the client processes macros, it generates value, which overrides value on the form. If the client does not process macros, it is ignored. Example { "type": "text", "name": "Ewallet", "label": "Account number", "hint": "Money will be credited to this account", "value_autofill": "currentuser_accountkey", "pattern": "[0-9]{11,33}" } Autofill macros: macro_name Description currentuser_accountkey Substitutes the account number of the Yandex.Money user, if known.

calendar_next_month Substitutes a yyyy-mm value in a month type field, for the next month after the current calendar month. currentuser_email Substitutes login@yandex.ru for an authorized user, if the login name is known. Defining dates and times Time calculations are based on the ISO 8601:2004 standard Defining the complete date format: date string. Format for specifying the complete date YYYY-MM-DD Defining the month and year format: month string. Format for specifying the month and year YYYY-MM Payment forms for purchasing products and services Yandex.Money API API for Apps 93

In the attributes of the date and month UI controls, you can specify: • The absolute value of the full date or the month and year.

• To use the current date (now). • A value calculated from the absolute date value and an interval. Example: Absolute date value 2014-08-19 Example: Substitute the current date now A value calculated from the absolute date value and an interval is defined in the section "4.4.4.2 Representations of time intervals by duration and context information" of the ISO 8601:2004 specification. Use Basic Format to define the interval (duration): PnYnMnD Where: • P — A period (dot). • nY — The number of years (for example, 3Y). • nM — The number of months (for example, 10M). • nD — The number of days (for example, 5D).

Note: Unused symbols can be omitted. For example, you can specify an interval as 3Y or 2M10D or 5D. To specify a date in the past, use the extended format defined in the section "4.4.4.4 Representations of time interval identified by duration and end" of the ISO 8601:2004 specification: PnYnMnD/YYYY-MM-DD or PnYnMnD/now To specify a date in the future, use the extended format defined in the section "4.4.4.3 Representations of time interval identified by start and duration" of the ISO 8601:2004 specification: Payment forms for purchasing products and services Yandex.Money API API for Apps 94

YYYY-MM-DD/PnYnMnD or now/PnYnMnD Example: The selected payment period must be no earlier than three years ago { "type": "month", "name": "period", "label": "Payment period", "required": true, "readonly": false, "min": "P3Y/now" } Example: The selected payment period must be no later than next month { "type": "month", "name": "period", "label": "Payment period", "required": true, "readonly": false, "max": "now/P1M" } Example: The selected date must be no earlier than 1 January 2005, and no later than 3.5 years after 2 January 2009 { "type": "date", "name": "document_date", "label": "Resolution date", "required": true, "readonly": false, "min":"2005-01-01", "max": "2009-01-02/P3Y6M" } Payment forms for purchasing products and services Yandex.Money API API for Apps 95

account-info 25 API 4 incoming-transfer-accept 47 incoming-transfer-reject 49 instance-id 55 OAuth 9 operation-details 31 operation-history 26 process-external-payment 58 process-payment 42 request-external-payment 56 request-payment 34 Yandex.Money 4 Index Yandex.Money API API for Apps

Yandex.Money API API for Apps 13.09.2018