From you - ideas of monetization of streaming and implementation of the Yandex.Money API, from us - the audience, advertising and money.

We decided to celebrate the sixth birthday of the API transfers with the anti-hackathon, where anyone can try their hand at fighting for the jackpot. In addition to the cash prize of 100,000 rubles, we will share with the winner a profit from transfers via Yandex.Money.

We invite under the cut all individual developers, entrepreneurs and start-up teams.

How to participate: you need to develop a ready-to-use solution for collecting money for streaming on the Web.

Why do we need it at all: the number of services with streaming paid content is steadily growing, and there is no convenient way to get money for them. At least one that would be convenient not only for the owner of the service, but also for the users.

How free is the creativity: the decision should involve payments through the Yandex.Money API, all the rest is up to you. A jury of experts from the company will select the best solution, and its authors will receive a prize of 100,000 rubles and will be able to pick up a commission of 0.5% from each operation of their service.

When we sum up: ready prototypes and we take your questionnaires until August 1, 2017 .

The API allows you to perform the following tasks:

• request a balance;

  
  

• view transaction history;

  
  

• transfer money between wallets;

  
  
• replenish the electronic wallet with a bank card.

To make it easier for you to immerse yourself in the solution of the problem, let’s take a look at examples of popular API usage scenarios.

# 1 Request access to transactions in the wallet

Before performing any operations with wallets in Yandex.Money (for example, viewing the history of operations or account status), the developer needs to obtain certain rights .

By the way, the authorization of applications in Yandex.Money meets the following specifications:

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

Register the application and specify its parameters. As the Redirect URI, specify the address to which Yandex.Money will send the user after successful OAuth authentication. After that you get your unique client_id .

Now you can request the rights to conduct the necessary actions with the wallets of users. An example of an authorization request with the right to view the history of operations of the wallet:

POST /oauth/authorize HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 191 client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ01&response_type=code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb&scope=account%2Dinfo%20operation%2Dhistory 

Upon authorization request, the user is redirected to the authentication page, where he enters a login password and can confirm or reject the list of requested rights:

Authorization interface

The result of the authorization is returned as HTTP 302 Redirect - the application will redirect the user to the Redirect URI address that the developer specified in the request parameters. The value of the Redirect URI must match the settings of the application, allowing the ability to add any additional parameters to the end of the line. The redirection address with the successful result of the authorization contains the parameter code - a temporary authorization token.

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

The last step is to get the token for which a certain set of rights is assigned. After that, the application changes the temporary token to an authorization token, which the developer will use to access information in the wallet:

 POST /oauth/token HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Content-Length: 421 code=0DF3343A8D9C7B005B1952D9B933DC56ACB7FED6D3F2590A6FD90EC6391050EDFFCC993D325B41B00F58E5383F37F6831E8F415696E1CF07676EE8D0A3655CDD7C667189DFB69BFDB7116C0329303AB2554290048BAF9B767B4C335BF0E85830AC017AD2F14D97F529893C202D3B2C27A61EE53DC4FB04DAE8E815DE2E3F865F&client_id=ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ01&grant_type=authorization_code&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb 

But this answer will come with a successful exchange of temporary token:

 HTTP/1.1 200 OK Content-Type: application/json Content-Length: 293 Cache-Control: no-store { "access_token":"410012345678901.0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ0123" } 

Access_token is a symmetric secret, so the application developer should take additional measures to protect it: keep the token in an encrypted form, provide access only if the owner passes the authentication successfully.

# 2 View transaction history

When the token is received, the developer can use it for authorized actions with the wallet. Let me remind you what exactly this authorization allowed to view the history in the user's wallet.

The simplest example from the field of crowdfunding in social networks: a certain VKontakte community dedicated to football - there are many subscribers and the activity is good, but this is a project made at leisure, and not a goal of life. At one time, the public held meetings of subscribers and collected money for this and other needs through the administrator’s electronic wallet. For greater transparency in the distribution of the money received, the administrator created a table and pulled in there data on the history of operations through the API. When someone sends money to the wallet, everyone sees the details of the operation, the sender and the purpose of the transfer.

To view the data, we use the operation-history method, which allows us to personalize the developer's request. At the output we get, for example, the last 10 transactions, or operations for the last six months, or only expense transactions. It all depends on the appetite of users for whom the developer creates the service.

In the case of tape drives, it is useful to display information on the date and time of the incoming deposit, including its amount, nickname and message of the sender, used payment method. The data is most often filtered by nickname, which can be useful for a streamer: for example, you can choose the best donater (subscriber) and encourage him to offer any game that will be distributed in the near future.

An example of a request to receive the last five incoming credits to a wallet looks like this:

 POST /api/operation-history HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.7EE34A50588723226C886A475AD1D415471BF687CCC2AFC7664BA12F4EC2BDBA1EB82625E49BC29D114A6C6AF12F87639A877E81A5B77B81F003A9DB4CCEB9BD80C6E70B157C18410E884465276AACBD58C2D7B6022CBDFD0004B80704E82D3F0E4039A29655EFAA44F037D6BF763B0B803329FE8A0E511057173B04341C4317 Content-Type: application/x-www-form-urlencoded records=5&type=deposition 

Here is what Yandex.Money service can answer:

 { "next_record": "5", "operations": [ { "operation_id": "548936732440013012", "title": "   ", "amount": 1.96, "direction": "in", "datetime": "2017-05-24T10:25:32Z", "label": "123007", "status": "success", "type": "deposition" }, { "pattern_id": "p2p", "operation_id": "1097872036856016025", "title": "  410012345678902", "amount": 0.99, "direction": "in", "datetime": "2017-05-24T10:13:38Z", "status": "success", "type": "incoming-transfer" }, { "operation_id": "548428048231013012", "title": "   ", "amount": 1.96, "direction": "in", "datetime": "2017-05-18T13:07:28Z", "status": "success", "type": "deposition" }, { "operation_id": "548427906481013012", "title": "   ", "amount": 1.96, "direction": "in", "datetime": "2017-05-18T13:05:06Z", "status": "success", "type": "deposition" }, { "pattern_id": "p2p", "operation_id": "1096319740674326025", "title": "  410012345678903", "amount": 0.01, "direction": "in", "datetime": "2017-05-15T10:37:50Z", "status": "success", "type": "incoming-transfer" } ] } 

Another example of a service based on a request for history is collective purchases on the forums: people agree to chip in and order something in bulk at a lower price, and the organizer collects money for his wallet. For everyone to see how many participants are in the purchase and how money is spent, you can use one of the many services based on the Yandex.Money API. It is enough for the collector to log in to the wallet in one of these services.

# 3 Balance Check

Game streamers often work with multiple monitors, so the Yandex.Money team developed a widget in which you can specify the purpose of collecting money, the required amount - and track progress. For example, a streamer wants to buy a new PlayStation 4. Once the required amount is collected in the wallet, Yandex.Money will send a notification to the widget that it’s time to make an order.

Accumulation widget.

Another example is when a streaming service needs constant access to the balance - a loyalty program: for example, you can place a pizzeria offer with a discount in your streamer’s personal account, where you can instantly order pizza. But before that, the service must make sure that there is enough money in the account to order.

To view the balance, you can use the account-info method :

 POST /api/account-info HTTP/1.1 Host: money.yandex.ru Authorization: Bearer 410012345678901.1578E01607EB3899853D2883E47841A195BC561F1F8CF479D593B662AD60B2D146EE49F02D750CB2972E51E0DF10369AE77FD930D82B7563AA0D65FA709A7C31EB59D4FFC1F2E85A14A817BDFB282C5A82FF1B79C65D2AE7B3BAE1C1C7D89CBE80477FF1C51A8F3DD9A032475BE629235949B7A2CA7823AC6AC06DB3176F9B54 Content-Type: application/x-www-form-urlencoded 

In response, the server will return the following:

 { "account": "410012345678901", "balance": 192.45, "currency": "643", "account_type": "professional", "identified": true, "account_status": "identified", "cards_linked": [ { "type": "MasterCard", "id": "4005641800", "pan_fragment": "532130******2227" } ], "balance_details": { "total": 192.45, "available": 192.45, "blocked": 1 } } 

As a result, you will receive not only detailed information on the balance, but also information about the attached bank cards: the masked card number, type, ID of the linked card.

# 4 Transfer from wallet

Using the API, you can initiate not only transfers from the wallet, but also from the linked card. This is convenient for instant settlements with people who do not keep money in their wallet and use it as an interlayer, so as not to shine a card on the Internet. At the same time, the payer is still in control of expenses, because even automatic debiting from the linked card must be authorized.

How it works:

1. After receiving confirmation from the user, the API will try to write off the requested amount from the wallet.

   
   

2. If there is not enough money on the balance, the service will respond not_enough_funds .

   
   
3. Further, the service can write off money from a card tied to a wallet, if the user has allowed it. Automatic debiting from the linked card is available only to legal entities. In addition, to write off money from the card will not work when transferring between wallets.

Streamers can motivate viewers to subscribe to regular transfers for public gratitude on the air or social networks, gifts or the right to choose the next game for stream.

Subscription is as follows:

1. Next to the “Support” button there can be a checkbox “Subscribe to a monthly payment in favor of this tape drive”.

   
   
2. When a user clicks on the “Support” button, the developer checks the condition of regular payments and adjusts the list of requested rights in the Yandex.Money request.

Since we are talking about the operation in the wallet, you need to request permission to conduct it - the request for access remains almost as in Example 1, but the scope changes.

The set of requested rights, which allows you to make a one-time transfer in the amount of 1000 rubles to the purse 410012345678901, is as follows:

 payment.to-account("410012345678901").limit(,1000) 

If the sender subscribes to regular payments, the authorization may have the following meaning:

 payment.to-account("410012345678901").limit(30,1000) 

Where 30 is the time period in days, 1000 is the total amount of payments for the period.

Sample request for regular write-off:

 POST /oauth/authorize HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded client_id=49414287408917F4BC735301F4731878533F409F3BA8EA055D0D441EE002F69B&redirect_uri=http%3A%2F%2Fexample.com%2Fapi%2Fredirect_uri.php&response_type=code&scope=payment.to-account(%22410012345678903%22).limit(30%2C1000) 

The sender will see a beautiful form:

After receiving the token, the developer needs to write off via the request-payment and process-payment methods:

 POST /api/request-payment HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Authorization: Bearer 410012345678901.D2E0917C3E09DE474DD3BF6288DDCB6818D55B6BBC8A9386ABA2A983F3F4666102F9B7A2D370D7079891299907368389F3BA8E2BE04597DCFF4CF02F4E3423896776D1C5CCE30A09B5D2E73874C5FE33CAE19286EAB03D146B46A188939BEC1ADA93F3530ECBFACA2591715F686EDBC9F616A7BF912CF4DC9CFB689473328347 pattern_id=p2p&to=410012345678903&amount=10&comment=Transfer+to+Nuke73&message=Transfer+from+SuperMan 

Sample answer:

 { "status": "success", "request_id": "333235373335343733345f646366303562383436613661306133373130663766343166303137666131336262656637353539655f323537353532373836", "recipient_identified": true, "multiple_recipients_found": false, "recipient_account_type": "professional", "recipient_account_status": "identified", "contract_amount": 10, "money_source": { "cards": { "allowed": false }, "wallet": { "allowed": true }, "card": { "allowed": "false" } } } 

Speaking of transfers and commissions. In your personal account, you can choose who pays a commission for the transfer - the amount and amount_due parameters are responsible for this. If the amount_due parameter is specified in the payment template, then this amount will go to the streamer wallet (commission paid by the viewer). If the streamer is ready to take it over, then the input parameter indicates the amount. Thus, the amount (amount to be transferred) is equal to the amount of commission and amount_due (amount receivable).

The transfer is performed after calling the process-payment method without the participation of the user, who once confirmed access when authorizing access. The request_id is the identifier from the request-payment method response.

 POST /api/process-payment HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded Authorization: Bearer 410012345678901.D2E0917C3E09DE474DD3BF6288DDCB6818D55B6BBC8A9386ABA2A983F3F4666102F9B7A2D370D7079891299907368389F3BA8E2BE04597DCFF4CF02F4E3423896776D1C5CCE30A09B5D2E73874C5FE33CAE19286EAB03D146B46A188939BEC1ADA93F3530ECBFACA2591715F686EDBC9F616A7BF912CF4DC9CFB689473328347 request_id=333235373335343733345f646366303562383436613661306133373130663766343166303137666131336262656637353539655f323537353532373836 

Sample answer:

 { "status": "success", "payer": "410012345678901", "payee": "410012345678903", "credit_amount": 9.95, "payment_id": "549038975018120011" } 

Excellent - the debit from the wallet was successful.

# 5 Transfer from a bank card

Transfer from a bank card is different from transfer from a wallet:

• First, it does not require an authorization request. To identify the card payment application, the developer registers his copy with Yandex.Money and obtains an instance_id using the same-name method ;

  
  
• Secondly, the sender somewhere you need to specify the details of your bank card. To display this form, the developer needs to create a payment based on a standardized template using the request-external-payment method, and then initiate the payment operation using process-external-payment .

If the transfer is completed successfully, the request-external-payment method will return the following:

 { "status": "success", "title": "   410011498692222", "contract_amount": 102.04, "request_id": "333235373135303437315f36313764393332336462393164373433353264303465346432626262313465353933363763333133", "money_source": { "payment-card": {} } } 

After receiving the request_id - a unique identifier for the payment context - you can initiate a payment transaction and redirect the user to the Yandex.Money form. To do this, use a POST request at the address acs_uri with the parameters acs_params, where the payer needs to specify the bank card details.

Request example:

 POST /api/process-external-payment HTTP/1.1 Host: money.yandex.ru Content-Type: application/x-www-form-urlencoded request_id=333235373135303437315f36313764393332336462393164373433353264303465346432626262313465353933363763333133&instance_id=hh2CVJWrU9uU7N2hpEh1LvjfyBAby8USyMUEF4DM8AS6w93o53M3xrlGHsMUiWTL&ext_auth_success_uri=http%3A%2F%2Fexample.com%2Fsuccess%2F&ext_auth_fail_uri=http%3A%2F%2Fexample.com%2Ffalse%2F&request_token=false 

And the answer is:

 { "status": "ext_auth_required", "acs_uri": "https://m.money.yandex.ru/internal/public-api/to-payment-type", "acs_params": { "cps_context_id": "333235373135303437315f36313764393332336462393164373433353264303465346432626262313465353933363763333133", "paymentType": "FC" } } 

Card form Yandex.Money.

Directly carrying the payment falls on the shoulders of Yandex. Money. After specifying the bank card details and clicking on the “Pay” button, the user will go to the 3-D Secure page of his issuing bank and, after entering the password, return to the developer's service: if the 3-D Secure authentication by the bank card is completed successfully, it will go to the page with payment confirmation (ext_auth_success_uri). If the issuing bank refused to authenticate, the user is redirected to the page with an error (ext_auth_fail_uri).

Redirect addresses can be specified by the developer when calling the process-external-payment method.

When the payer goes to the success page after checking 3-D Secure, you need to make sure that the authorization on the bank card was also successful. To do this, the developer re-invokes process-external-payment with the previously received request_id .

Sample answer:

 { "status": "success", } 

Usually, card authorization occurs within 10-20 seconds after authentication. If at the time of the process-external-payment re-call we did not receive the authorization status from the bank, the developer will know about it.

An example of a similar answer:

 { "status": "in_progress", "next_retry": "5000" } 

Next_retry is the recommended time in milliseconds when the request should be repeated. The field is present only in the in_progress status.

Additional features: form and button designer

The payment solution using the API requires some effort and complex technological interaction. A simpler option is to use ready-made custom Yandex.Money forms : the information about the transfer is broken down into parameters and transmitted by the POST method to a special address.

An example of the interface of the form of transfers to the Yandex streamer wallet.

The translation script using a custom form looks like this:

1. The sender chooses how to transfer money - from an electronic wallet or from a bank card.

   
   

2. The developer generates a string from the Yandex.Money parameters set and sends them by the POST method to money.yandex.ru/quickpay/confirm.xml along with a unique payment label (label) for further identification. The developer keeps the details of the operation in his database.

   
   

3. The payer proceeds to the page for selecting the payment method and confirming the transfer on the Yandex.Money side, and the amount is debited and credited to the tape drive's purse. Of course, minus the commission.

   
   

4. The recipient will know about the receipt of funds through the HTTP-notification, email, SMS, push. The address of the notification handler to the recipient must be specified in the wallet settings in advance.

   
   
5. The developer analyzes the details received at the address of the processor and decides on further actions. In our case, if the incoming amount satisfied the conditions of the tape drive, a subscriber message with an animated accompaniment was transmitted in its video stream. The message was reproduced using SpeechKit technology.

In this scenario, there is one drawback: for normal operation of the service, streamer requires extra manipulations with the settings of HTTP notifications inside the wallet.

Unlike the API, the forms and buttons allow you to transfer money from a linked bank card. However, the commission is taken only from the recipient .

In order not to require unnecessary manipulations from the tape drive, it is enough to learn to look at its history of operations and match the unique translation label with the data from the database. It remains only to get access to the tape drive operations, for which, at the very beginning of the article, we asked the tape drive to confirm access to account-info and operation-history rights. The first method will help us find out the wallet number of the tape drive, the second - information on operations.

Here is the answer to the request of the last two operations in the streamer wallet through the API using the operation-history method (the translation was received through a customized form):

 { "next_record": "2", "operations": [ { "operation_id": "549575176734053012", "title": "   ", "amount": 49, "direction": "in", "datetime": "2017-05-31T19:46:16Z", "label": "yadonate#1782", "status": "success", "type": "deposition" }, { "pattern_id": "p2p", "operation_id": "1098088627442030025", "title": "  410011498790000", "amount": 9.95, "direction": "in", "datetime": "2017-05-25T16:18:33Z", "label": "testpayment", "status": "success", "type": "incoming-transfer" } ] } 

After checking the success of the transfer to the Streamer wallet, you can create your favorite magic in the video stream.

In this post, we looked at only the most basic ideas and scenarios for using the API for streaming services. If something is not clear, feel free to ask in the comments. And if among readers there are streamers or their viewers - share your opinion on how to make donations more convenient and more fun.

You can register for participation on Yandex.Events . Prototypes and questionnaires are accepted until August 1, 2017.

By screws!