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.
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: firstname.lastname@example.org 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