Yandex.Money API API for Apps

(1)

Yandex.Money API

API for Apps

(2)

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

(3)

... 4

Application authorization flow

... 5

App registration

... 7

Authorization Request

... 7

Access token request

... 9

Revoking a token

... 11

Access token scope

... 12

Protocol overview

... 16

Request format

... 16

Response format

... 17

Data types

... 18

Information about a user's account

... 20

account-info method

... 20

operation-history method

... 22

operation-details method

... 26

Payments from the Yandex.Money wallet

... 29

request-payment method

... 29

process-payment method

... 36

incoming-transfer-accept method

... 41

incoming-transfer-reject method

... 43

Payments from bank cards without authorization

... 45

instance-id method

... 49

request-external-payment method

... 50

process-external-payment method

... 52

Notification of events

... 56

Notification of incoming transfer

... 56

(4)

The API for Apps is a tool for using almost all of our service's functions.

What you can do using the API:

• Accept payments — both merchants and individual users. Money can be deducted from any bank card

or Wallet.

• Get information about users — check the balance and get the history and details of operations.

• Get HTTP notifications — for automatically processing transfers.

• Perform direct debits. Made from the user's wallet by default, or from a bank card by agreement.

How to get started

1. Register your app

in the Yandex.Money API.

2. Read the documentation.

3. Add the new payment feature to the app. For a quick start, use our SDK —

PHP

,

Java

,

Android

,

ObjC

,

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

(5)

Application authorization flow

To begin working with a “Yandex.Money” user's account, an application must get authorized using the OAuth2

protocol, which 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 approved 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.

This is the Registration Request in the OAuth2 protocol. 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 method. The client_id remains constant during the entire application

lifecycle.

(6)

How a user authorizes an application

1. The application initiates user authorization to access the user's account, by sending the

Authorization

Request

to the Yandex.Money server.

2. Yandex.Money redirects the user to the Yandex.Money authentication page.

3. The user enters his login and password, reviews the

list of requested permissions

, and either approves

or rejects the authorization request.

4. The application receives an Authorization Response in the form of an HTTP Redirect with either a temporary

authorization code or an error code.

5. The application uses the temporary authorization code to get an access token (

Access token request

).

6. The response contains the permanent access_token.

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

(7)

App registration

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

1. Go to the

App registration

page. To get access, you will need to enter your payment password.

2. Set the application parameters:

description

The name of your application, for example, "Mobile store".

application_uri

Link to the application's web page or the developer’s web site.

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: m.sp-money.yandex.ru (for mobile devices) or sp-money.yandex.ru (for all other devices)

Content-Type: application/x-www-form-urlencoded Content-Length: <content-length>

client_id=<client_id>&response_type=code &redirect_uri=<redirect_uri>&scope=<scope>

(8)

client_id=092763469236489593523464667 response_type=code redirect_uri=https://client.example.com/cb scope=account-info operation-history

Request example:

POST /oauth/authorize HTTP/1.1 Host: sp-money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 154 client_id=092763469236489593523464667&response_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.

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!

If a user repeats the application authorization with the same value for the client_id parameter, the previous

authorization is canceled.

HTTP Redirect callback parameters:

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:

(9)

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.

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).

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. The temporary code expires after 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.

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.

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: m.sp-money.yandex.ru (for mobile devices)or sp-money.yandex.ru (for all other devices)

Content-Type: application/x-www-form-urlencoded Content-Length: <content-length>

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

(10)

POST /oauth/token HTTP/1.1 Host: sp-money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 145 code=i1WsRn1uB1ehfbb37&client_id=092763469236489593523464667&grant_type=authoriz ation_code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

Request example with authenticity verification using a secret word:

POST /oauth/token HTTP/1.1 Host: sp-money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 179 code=i1WsRn1uB1ehfbb37&client_id=092763469236489593523464667&grant_type=authoriz ation_code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom %2Fcb&client_secret=my_secret_word

Request parameters:

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):

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).

(11)

HTTP/1.1 200 OK Content-Type: application/json Content-Length: 102 Cache-Control: no-store { "access_token":"SlAV32hkhjhkkefhkjGHGSDcbndbjhfSHDFhjdbfv...wfervnrjKG" }

Example of error response:

HTTP/1.1 400 Bad Request Content-Type: application/json Content-Length: 31 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.

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.

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:

(12)

POST /api/revoke HTTP/1.1 Host: money.yandex.ru

Authorization: Bearer 01234567890ABCDEF01234567890 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.

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

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

(13)

money-source Available payment methods (see the methods request-payment and process-payment). For more information, see The money-source permission.

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. Mandatory parameter.

Tip:

Mobile phone number as the payee ID.

If the user who is receiving the transfer has a mobile phone linked to the account, the linked phone number

can be used as the payee ID instead of using the account number. 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:

(14)

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.

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.

(15)

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, 50 kopecks per day, and the user can change the amount.

.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","cards")

Example of payment using only a linked bank card:

money-source("cards")

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","cards")

(16)

Protocol overview

• Request format

• Response format

• Access token scope

• Data types

Request format

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

https://money.yandex.ru/api/<method_name>

Requests are authorized in accordance with

The OAuth 2.0 Authorization Framework: Bearer Token Usage

.

HTTP requests must have this header:

Authorization: Bearer <access_token>

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.

• Character encoding: UTF-8.

Request example:

(17)

POST /api/request-payment HTTP/1.1 Host: money.yandex.ru

Content-Type: application/x-www-form-urlencoded Authorization: Bearer 01234567890ABCDEF01234567890 param1=value1&param2=value2&param3=value3

Response format

Access token scope

Data types

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 standard

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

(18)

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"

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.

Request format

Access token scope

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).

(19)

Description of the datetime format:

• YYYY — Year, always 4 digits.

• MM — Month, always 2 digits (01 for January, and so on).

• 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:

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

Date and Time on the Internet: Timestamps

Request format

Response format

Access token scope

(20)

Information about a user's account

• account-info method

• operation-history method

• operation-details method

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

available amount Amount available for payments.

deposition_pending amount The amount of funds pending deposit. 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.

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 01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF Content-Type: application/x-www-form-urlencoded Content-Length: 0 Response example:

(22)

{ "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" } ], "services_additional":[ "link_alfabank" ] }

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 later than

or equal to the from value). 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

(23)

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.

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 or greater

than from and less than till.

2. If both the from and till conditions are set, records are selected for the time period equal to or greater

than from and less than till.

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.

(24)

Parameter

Type

Description

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.

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.

The necessity of an incoming-transfer-accept/ incoming-transfer-reject call is determined by the status=in_progress field.

incoming-transfer-protected Incoming transfer with a secret code.

The necessity of an incoming-transfer-accept/ incoming-transfer-reject call is determined by the status=in_progress field.

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).

(25)

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: POST /api/operation-history HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF 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 01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF01234567890ABCDEF 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" : "Direct phone account top-up 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" }

] }

(26)

{ "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 of ADSL Internet access to company XXX\nCustomer account no.: \n1234567/89\nPayment 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 donuts",

"comment" : "Transfer to Yandex.Money user", "codepro" : false,

"details" : "Recipient account:\n4100123456789\nAmount: 50,00 rubles", "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.

(27)

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 (for the sender). Present in the sender's transfer

history.

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 to other users 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 from/to other users 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.

(28)

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:

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 01234567890ABCDEF01234567890 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 My Provider Company",

"details" : "Prepayment of ADSL Internet access to Company \"XYZ\"\nCustomer account no.: \n1234567/89\nPayment amount: 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 donuts",

"comment" : "Transfer from Yandex.Money user", "codepro" : false,

"details" : "Recipient account:\n4100123456789\nAmount: 50,00 rubles", "type" : "payment-shop"

}

Response example for nonexistent operation request: {

"error" : "illegal_param_operation_id" }

(29)

Payments from the Yandex.Money wallet

Payment flow in Yandex.Money:

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 payment contract text.

3. The application shows the payment contract text 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:

• payment to a merchant

• transfer of funds to other users' 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

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

.

(30)

Arguments for making a payment to a merchant

Parameter

Type

Description

pattern_id string Payment Pattern ID.

* string User parameters for the Payment Pattern that are 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.

amount_due amount Amount to receive.

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.

Tip:

The transfer amount is credited to the recipient minus the transfer fee. The sender of the transfer can set only

one of these parameters:

• amount — payment amount that will be deducted from the sender's account

• amount_due — received amount that will be credited to the recipient's account

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

(31)

Parameter

Type

Description

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

will be entered 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.

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; acceptable 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 currency used on the payer's account. Present only on success.

(32)

Parameter

Type

Description

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 User account type in Yandex.Money. This parameter is present if the method was successfully executed when transferring funds to another 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.

Operation processing result codes:

Code

Description

success Success.

refused Payment refused; the reason is explained in the error field. Final state.

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”

(33)

Code

Description

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.

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.

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 • AmericanExpress • 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".

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 }