The translation was generated automatically and may contain mistakes

The sale of virtual VKontakte

When selling virtual values, the VKontakte sends notifications to the application server to receive information about the object being sold and to confirm the purchase. Notifications are POST requests that are sent to callback address specified in the settings of your application. The structure of requests-notifications is considered in the section Processing of payment notifications .

How to Sell Virtual Goods

Step 1. Prepare the server side of the application

1.

On the application server, determine the URL to which requests related to purchases will come. It could be an address https://{ваш-сервер}/purchase Or any other.

In the server code, add a POST request handler that will arrive at that URL. To work with payments for goods, it is necessary to process the following notifications:

Notifications	Description
`get_item`	The VKontakte sends this notification to obtain information about the product for display in the purchase window: name, cost, image.
`order_status_change`	This notice is used when buying and returning goods.

More information about creating processors — in the section Processing of payment notifications .

3.
Implement on the server verification of the accrual of goods on a unique order_id and order status:
- •
  Add the goods to each order_id Only once.
- •
  If you receive repeated notifications in which the status of the order is the same, and order_id Return the same successful answer as at the first charge.
  This will help to avoid re-charges of goods.

Step 2. Specify the callback address in the application settings

1.

Go to the application settings. For this in list of Apps Find your mini-app or game and click Settings .
2.
Select the section Payments Menu on the left.
- •
  
  In the field URL for payment notifications VKontakte Specify the URL to which the site will send notifications. You identified him on step 1 .
- •
  
  New versions of the platform may introduce changes to the notification data structure. In the field API version Specify the version of notifications that your server supports.
- •
  
  To make payment in test mode in the field Payment Testers Indicate the users who will test the payments. In advance, these users should be added to the application administrators and give them the right to test.
  
  Adding administrators to this list is mandatory for testing. Without this, payment testing is not available even to full-access administrators. More information about the test settings — in the section Testing of Payments .

Step 3. Call the VK Bridge event to show the purchase window

To sell the game product, call the event VKWebAppShowOrderBox in the client part of the game. For example:

JavaScript

bridge.send('VKWebAppShowOrderBox', 
  { 
    type: 'item', // ?1?’сегда должно быть 'item'
    item: 'sale_item_id_1', // Идентификатор товара
  })
  .then( (data) => {console.log('Покупка состоялась.', data) }) 
  .catch( (e) => {console.log('Ошибка!', e) });

Note that if you’re not using any builder like webpack, and include a .js file of the VK Bridge library in the HTML code of your pages, you should use the name of the object in your JavaScript code vkBridge , not bridge .

The results can be verified not only by then and catch but also through events. More details in section Processing of results .

The order of processing of responses to the notification depends on the platform:

•

In the desktop version of the VKontakte site, your application receives an event VKWebAppShowOrderBoxResult only after the VKontakte platform has processed the response to the notification. If the application server reports an error in the response to the payment notification, the VKontakte sends an event VKWebAppShowOrderBoxFailed .
•

On Android and the mobile version of the site, your app always receives an event VKWebAppShowOrderBoxResult after the user confirms the payment by votes. VKontakte waits for a response to the notification, but does not send the event VKWebAppShowOrderBoxFailed even if the application returns the error code.

Data exchange

The data exchange takes place in two stages:

1.
To show a purchase window, your app needs to trigger an event.. VKWebAppShowOrderBox Libraries VK Bridge .

Receiving product data
- •
  
  The library sends a request to the VKontakte about the need to show the dialog box.
- •
  
  The site responds by sending a type notification to the application server get_item to get information about the product.
  
  In the parameter site The name of the place where the purchase is made. Consider this value when calculating the cost of goods in votes or OK.
- •
  
  The application server responds to this request and informs VKontakte customer of the name of the product, its cost and other data .
- •
  
  The site checks whether the user has enough votes on the account.
  
  If there are enough votes, the platform will show a dialog box to confirm the payment.Think of it as the most typical......
  
  If there are not enough votes, the VKontakte will offer the user to buy them with a bank card or an electronic wallet. After the purchase of votes, the exchange of data between the VKontakte and the application server takes place in the same way as in the case of a sufficient number of votes on the account.
2.
After the user clicks Pay up In the purchase window, the following happens:

Exchange of data after payment confirmation
- •
  
  VKontakte sends a notification to the application server orders_status_change . It says that the user has paid for the goods.
- •
  
  The application server provides the user with the purchased product and returns a VKontakte response about the successful processing of the order.
- •
  
  The VKontakte transfers votes from the user account to the application account, and also informs the client part of the application about a successful purchase.
  
  The application, in turn, can perform any actions that visually show the user that the purchase took place.

Return of goods

The procedure for returning the goods is initiated by the VKontakte Support. The user and the application cannot do this themselves.

When returning the goods, the VKontakte will send a notification to the application server order_status_change .

Test mode

Before making the app available to a wide range of users, it is important to test purchases and payments in it. Test payments are enabled automatically after a game or mini-app is created. Work mode will be enabled after moderation. More details in section Testing of Payments .

Working with a list of orders

All information about orders and payments is stored on the VKontakte servers. To work with the order list, you can use group API operations.. Orders .