The translation was generated automatically and may contain mistakes

How to make a payment

The section describes connecting the VK Pay payment window and making payments in mini-applications.

Use events to display the payment window the VK Bridge Library . VK Bridge allows mini-applications to interact with the API of the VKontakte and API of the operating system installed on the user's device.

Before calling the payment window, connect VK Bridge and read about using the library and calling events in the documentation VK Bridge — The First Steps .

Step 1. Initialize your application

To work with VKontakte via VK Bridge, initialize your application: send an Event VKWebAppInit With help method bridge.send Annex VKontakte

Step 2. Check the initialization result

Use an object to process the result Promise which returns a challenge.. bridge.send(...) or events VKWebAppInitResult and VKWebAppInitFailed . More specifically, in documentation VKWebAppInit .

If initialization succeeds, the VKontakte application will return object Promise or event VKWebAppInitResult with the field result: true .

In the event of an initialization error, the VKontakte application will return object Promise or event VKWebAppInitResult with information about the Error .

Step 3. Send a request to display the payment window VK Pay

To display the VK Pay payment window, send an Event VKWebAppOpenPayForm With help method bridge.send Annex VKontakte In the event, pass the mandatory parameters :

•
app_id The mini-app ID.
•
action type of translation. Always.. pay-to-service Transfer in favor of a legal entity.
•
params — fields of payment form VK Pay — depend on the type of transfer action . More details in section Payment parameters .

Important! If users receive a cashback for purchases in your store, the size and term of crediting of the cashback should be transferred at the time of calling the payment form in object params.data.cashback . You need to calculate the cashback amount before the user makes a payment.

**Example of a request to open a payment window with action: 'pay-to-service' **

JavaScript

bridge.send('VKWebAppOpenPayForm', {
    app_id: 6909581,
    action: 'pay-to-service',
    params: {
      user_id: 743784474,
      description: `Test Payment`      
    }})
  .then((data) => {
    if (data.status) {
      // Экран VK Pay показан
    }
  })
  .catch((error) => {
    // Ошибка
    console.log(error);
  });

In the case of a successful call to the payment window, the VKontakte adds information about the payment type and application signature to the request and sends a request to VK Pay. VK Pay checks the wallet data, user authorization, app and seller signature, forms a link to the payment window, signs a link and displays the payment window to the user via a link in the iframe.

If something goes wrong when calling the payment window, it will appear in the browser console error .

Step 4. Check the result of the payment window call

The VKontakte app will return object Promise or event VKWebAppInitResult with the following data:

•
status: true Information about the result of the payment ( true The payment is successful, false The payment is unsuccessful). If the user has closed the payment form without paying for the purchase, then status will equal false .
•
transaction_id ID of the transaction.
•
amount The amount of payment.
•
extra Additional information from the seller. Contains data object params.data .

In case of payment error, the VKontakte will return object Promise or event VKWebAppInitResult with information about the Error .

Step 5. Get a payment notification about the result of payment

If the payment is successful and you notifications are connected VK Pay will send the transaction result information to your URL.

Check the signature of the notification using the public key of the payment system, which you received when you connected. Decipher the notification data, process and send the system API response with the result of processing.

From the client side, the mini-app will send to your community a VKontakte message on behalf of the user who paid for the purchase. More details in section Tracking the status of payment .

Important! Events that come from a mini-app and VK Bridge do not guarantee a successful payment. The decision to provide a product or service should be made only on the basis of payment Notifications which VK Pay will send to your URL.

Payment parameters

Payment options for VK Pay depend on type of payment action . An example of parameter generation in JavaScript can be found here.. .

Object `params`

Field	Type	Description
`amount` Unnecessary	`integer` / `number` / `string`	Amount of payment in format `00.00` . The minimum amount is 1 ₽. The field can be transmitted as an integer, a floating point number (no more than two decimal places, among them insignificant zeros are not allowed) or a string (no more than two decimal places, insignificant zeros are allowed). The field is mandatory for fixed payments in favor of a legal entity: the field value `action` — `pay-to-service` . Field `amount` participates in the formation `merchant_data` for signature of the seller .
`description` Mandatory	`string`	The payment description for the user is the text that will be shown in the payment window. Format: string in UTF-8 encoding, up to 50 characters.
`action` Mandatory	`string`	type of translation. Always.. `pay-to-service` Transfer in favor of a legal entity.
`merchant_id` Mandatory	`integer`	Your seller ID in the VK Pay payment system, which was issued when you connected to VK Pay together with the seller’s private key.
`version` Mandatory	`integer`	version of the payment system. Current version: `2` .
`sign` Mandatory	`string`	Sign the mini-app VKontakte that calls the payment window. Details in the section How to create an application signature .
`data` Mandatory	`object`	Payment service data. In this JSON object, you pass the required fields for payment validation by the payment system, and you can pass any number of arbitrary fields you want to see in the payment notification. Description of fields - in the section Object `data` .
`user_id` Unnecessary	`integer`	User ID. Required for payments to the user: field value `action` always `pay-to-service` .

**Example object params **

JSON

{ 
    "amount": 1.5, 
    "data": { 
        "currency": "RUB", 
        "merchant_data": "eyJvcmRlcl9pZCI6IjI1NTMxIiwidHMiOiIxNTM5MzI5NzcwIiwiYW1vdW50IjoxLjUsImN1cnJlbmN5IjoiUlVCIn0=", 
        "merchant_sign": "63d5dce9d2c9d29198ba12ba3f8e270e6606a221", 
        "order_id": "25531", 
        "ts": "1539329770" 
     }, 
    "description": "Test Payment", 
    "action": "pay-to-service", 
    "merchant_id": 617001, 
    "version": 2, 
    "sign": "818964335a550e39d9a1dd0d752e60ab" 
}

Object `data`

data is a JSON object with a set of fields for validating the payment (e.g., order number and seller’s signature), as well as any arbitrary fields that the seller may need to process the order (e.g., delivery method data). Other fields in section Object params . Contents data Returned to payment Notifications in the field merchant_params .

Important! Names of Fields Within data They should be sorted alphabetically.

Field	Type	Description
`order_id` Mandatory	`integer` / `string`	An order ID on your system. Each payment window should be unique. Re-request with already processed `order_id` will be ignored. Field `order_id` participates in the formation `merchant_data` for signature of the seller .
`ts` Mandatory	`number`	Time stamp of request formation. Format: Number, Unix Timestamp . Time `ts` There should be less time to send a request to display the payment window, but not more than an hour. Field `ts` participates in the formation `merchant_data` for signature of the seller .
`currency` Mandatory	`string`	Currency of payment by ISO 4217 . It is currently supported only `RUB` . Field `currency` participates in the formation `merchant_data` for signature of the seller .
`merchant_data` Mandatory	`string`	BASE64-line for formation signature of the seller . Formed from a JSON object, which includes the fields of the payment window: `amount` , `cashback` , `currency` , `order_id` and `ts` . There should be no other fields in the JSON object.
`merchant_sign` Mandatory	`string`	SHA1-Signature of the Seller.
`cashback` Unnecessary	`object`	Cashback data. If there is no cashback, there is no need to transfer data. Description of fields - in the section Object `cashback` . Field `cashback` participates in the formation `merchant_data` for signature of the seller .

Object `cashback`

Object cashback contains the cacheback data. If you don’t have a cacheback, you don’t need to pass the object.

If users receive a cashback for purchases in your store, the amount and charge time data are transferred from the mini-app together with other payment window parameters and participate in the payment process.. formation of the signature of the seller merchant_sign . The order to write off the specified amount of cashback at the specified time is formed at the time of the transaction and cannot be changed except in cases of cancellation of the purchase (return of funds to the user).

Object cashback Entering into object params.data . Other fields in section Object params .

Field	Type	Description
`pay_time` Unnecessary	`integer`	Time to transfer cashback to Unix Timestamp . The time must be greater than or equal to the payment time.
`amount_percent` Unnecessary	`integer`	The amount of the cashback as a percentage of the payment amount, if the value is not transferred `cashback.amount` . Maximum value: `5` .
`amount` Unnecessary	`number`	Cashback amount in currency of payment, unless value transferred `cashback.amount_percent` . The maximum amount is 5% of the payment amount.