Уведомления

Уведомления посылаются сервером платёжной системы на Адрес обратного вызова,

указанный в настройках Вашего магазина, по протоколу HTTP или HTTPS, в
зависимости от протокола указанного в адресе обратного вызова, методом POST в
кодировке UTF-8. Уведомление подписывается секретным ключом, известным только
продавцу и платежной системе, чтобы исключить возможность подделки уведомления
(см. Подпись уведомления).

При отсутствии корректного ответа от сервера магазина в случае, если уведомление

синхронное, заказ будет аннулирован, если уведомление асинхронное, оно будет
отправляться снова, пока не истечёт срок действия заказа, после чего заказ будет
аннулирован. В данный момент все уведомления - синхронные.

Задано несколько типов уведомлений:

 Проверка наличия и стоимости товаров. Продавец сверяет список товаров и

возвращает его обратно платежной системе с внесенными изменениями (только для
сервиса Список желаний).
 Резервирование товара. Используется в сервисе Список желаний, посылается
платежной системой в момент полной оплаты товара друзьями пользователя,
добавившего товар в свой список желаний.
 Отмена резервирования товара. Используется в сервисе Список желаний, когда
желание, на которое уже собраны деньги (и, соответственно, послано уведомление
Резервирование товара) удаляется пользователем.
 Запрос на вычисление способов и стоимости доставки. Продавец вычисляет
возможные способы доставки заказа и их стоимость, и возвращает её платежной
системе.
 Изменение статуса заказа. В параметрах уведомления передается новый статус
заказа.

Внимание! Уведомления резервирования и отмены резервирования обрабатывать не

обязательно, можно просто возвращать на них успешный ответ, если резервирование в
Вашем магазине не требуется. Для оплаты товаров с Вашего сайта достаточно
обрабатывать только последние два типа уведомлений, для сервиса списоков желаний и
использовании каталога товаров необходимо также обрабатывать проверку наличия и
стоимости товаров.

Возвращаемые данные зависят от статуса заказа. В качестве ответа возвращается либо

результат обработки в случае успеха, либо описание ошибки в случае неуспеха (см.
Формат ответа в случае ошибки).

Общие параметры уведомления

Имя Тип Примечание
notification_type string тип уведомления
check-items-availability - проверка наличия и стоимости
товаров
item-reservation - резервирование товара

1
 calculate-shipping-cost - запрос на вычисление стоимости
доставки
order-state-change - изменение статуса заказа
merchant_id int идентификатор продавца
sig string подпись уведомления (см. Формирование подписи)
Параметры позиций заказа, переданные продавцом
item_id_1...N string идентификатор позиции
item_price_1...N stringстоимость
item_quantity_1...N stringколичество
item_currency_1...N stringчисловой код валюты в формате ISO 4217
item_currency_str_1..Nstringстроковый код валюты в формате ISO 4217

Эти параметры присылаются для всех типов уведомлений. Все параметры передаются в
кодировке UTF-8. Описание типов см. в разделе Типы данных.

Формат ответа в случае ошибки обработки

<?xml version="1.0" encoding="UTF-8" ?>
<failure>
<error-code>код ошибки</error-code>
<error-description>описание ошибки</error-description>
<error-parameters>(необязательный) параметры ошибки</error-parameters>
<critical>критичность ошибки</critical>
</failure>

Внимание! При корректной работе ошибок обработки возникать не должно. Скажем, если
обрабатывается уведомления способов и стоимости доставки (calculate-shipping-cost), а
Ваш магазин не доставляет товары по адресу с указанным индексом, то необходимо
просто вернуть пустой список вариантов доставки. Все ошибочные ответы логируются и
доступны во вкладке Логи при редактировании Вашего магазина.

Параметры ответа:
Имя Тип Значение
код ошибки int числовой код ошибки (см. Обработка ошибок)
описание описание ошибки в текстовом виде для чтения человеком,
string
ошибки обязательно для ошибок задаваемых продавцом
параметры необязательный параметр: параметры ошибки, передаваемые на
string
ошибки fail_url, максимальная длина 500 символов
 true, если повторение уведомления с такими же параметрами
приведёт к такой же ошибке (например, указанного товара не
существует в системе продавца). Уведомление не будет
отправляться повторно.

критичность
boolean
ошибки
 false, если ошибка временная и уведомление может быть
обработано позже (например, временная ошибка записи в
базу данных продавца). Уведомление будет отправлено через
некоторое время.

2
Формирование подписи
Параметр sig равен md5 от конкатенации пар имя параметров=значение параметра,
расположенных в порядке возрастания имени параметра (по алфавиту) и секретной
подписи, указанной в настройках Вашего магазина. При несовпадении необходимо
выдать в ответе ошибку 10, "Несовпадение вычисленной и переданной подписи" (см.
Обработка ошибок).

Пример формирования подписи с секретным ключом W7kVvxVxZ4:

sig = md5("name1=value1name2=value2W7kVvxVxZ4")

Типы данных
int целое число (32 бита)
double число с десятичной точкой (в качестве разделителя всегда используется ".")
string строковые данные
booleanбулевый тип ("true", "false", 0, 1)

3
Проверка наличия и стоимости товаров
(только для сервиса Список желаний)

Это уведомление посылается перед резервированием товара, перед оформлением заказа

или по инициативе пользователя. Оно используется для проверки наличия товара в
магазине и уточнения его стоимости.

Параметры уведомления:
Имя Тип Примечание
notification_type stringравен "check-items-availability"
(есть только при проверке желания) идентификатор желания,
wish_id int
уникален для конкретного пользователя (user_id, см. ниже)
merchant_id int идентификатор продавца
sig string подпись уведомления (см. Формирование подписи)
Параметры позиций заказа, переданные продавцом
item_id_1...N string идентификатор позиции
item_price_1...N stringстоимость
item_quantity_1...N stringколичество
item_currency_1...N stringчисловой код валюты в формате ISO 4217
item_currency_str_1..Nstringстроковый код валюты в формате ISO 4217
Информация о пользователе
(есть только при проверке желания) id пользователя
user_id int
ВКонтакте, совершающего оплату
shipping_email string(есть только при проверке желания) контактный e-mail

В ответ должен прийти тот же список товаров, но с внесенными корректировками.

Корректировки могут включать в себя:

 Изменение цены на единицу товара, если цена изменилась с момента последнего

обновления цены в каталоге.
 Изменение количества единиц товара в сторону уменьшения, если необходимого
количества товаров нет на складе магазина.
 Может быть передан параметр last со значением 1, если этого товара больше не
будет появляться на складе. Таким образом, если товара временно нет на складе, то
quantity будет 0, а last не будет указан, если же товара нет и не предвидится на
складе (к примеру, его сняли с производства и поставки), то quantity будет 0, а last
будет 1.

Формат ответа:
<?xml version="1.0" encoding="UTF-8" ?>
<items>
<item id="идентификатор товара" last="либо 1 либо не указывается">
<price currency="код валюты">текущая стоимость единицы товара</price>
<quantity>доступное количество единиц товара</quantity>
</item>
...
</items>

4
Параметры ответа:

Имя Тип Примечание

идентификатор товара в системе магазина; набор этих
идентификатор
string идентификаторов в ответе на уведомление должен повторять набор
товара
идентификаторов в параметрах уведомления.
текущий код
stringчисловой или строковый код валюты в формате ISO 4217
валюты
стоимость
stringстоимость единицы товара в указанной валюте
единицы товара
количество единиц данного товара, которое имеется в наличии;
может быть меньше или равно количеству, переданному в
количество
string параметрах уведомления; может быть равно нулю, если товара нет
единиц товара
в наличии; параметр last указывает на то, будет ли этот товар
доступен в будущем, или его поставка прекращена.

Если цена изменилась, то она обновляется и в списке желаний пользователя, после этого
ему либо нужно собрать недостающую сумму, либо ему уже хватает и он может перейти к
оформлению заказа.

5
Резервирование товара
(только для сервиса Список желаний)

Это уведомление посылается в тот момент, когда друзьями пользователя собрана вся
необходимая сумма и ожидается, что пользователь вскоре начнет оформлять заказ. Перед
этим уведомлением всегда посылается уведомление проверки наличия и стоимости
товара. Если в результате проверки товар есть в наличии и собранной суммы достаточно
для текущей цены товара, то посылается уведомление резервирования товара.

Параметры уведомления:
Имя Тип Примечание
notification_type stringравен "item-reservation"
идентификатор желания, уникален для конкретного
wish_id int
пользователя (user_id, см. ниже)
merchant_id int идентификатор продавца
sig string подпись уведомления (см. Формирование подписи)
Параметры позиций заказа, переданные продавцом
item_id_1...N string идентификатор позиции
item_price_1...N stringстоимость
item_quantity_1...N stringколичество
item_currency_1...N stringчисловой код валюты в формате ISO 4217
item_currency_str_1..Nstringстроковый код валюты в формате ISO 4217
Информация о пользователе
user_id int id пользователя ВКонтакте, совершающего оплату
shipping_email stringконтактный e-mail

В случае успешного ответа возвращается <reservation-success />.

Формат ответа:
<?xml version="1.0" encoding="UTF-8" ?>
<reservation-success />

6
Отмена резервирования товара
(только для сервиса Список желаний)

Это уведомление посылается в тот момент, когда друзьями пользователя собрана вся
необходимая сумма, а пользователь после этого удаляет желание. Оно посылается
независимо от успешности ответа на уведомление о резервировании товара.

Параметры уведомления:
Имя Тип Примечание
notification_type stringравен "cancel-item-reservation"
идентификатор желания, уникален для конкретного
wish_id int
пользователя (user_id, см. ниже)
merchant_id int идентификатор продавца
sig string подпись уведомления (см. Формирование подписи)
Параметры позиций заказа, переданные продавцом
item_id_1...N string идентификатор позиции
item_price_1...N stringстоимость
item_quantity_1...N stringколичество
item_currency_1...N stringчисловой код валюты в формате ISO 4217
item_currency_str_1..Nstringстроковый код валюты в формате ISO 4217
Информация о пользователе
user_id int id пользователя ВКонтакте, совершающего оплату
shipping_email stringконтактный e-mail

В случае успешного ответа возвращается <reservation-cancelled />.

Формат ответа:
<?xml version="1.0" encoding="UTF-8" ?>
<reservation-cancelled />

7
Запрос на вычисление способов и стоимости
доставки
Используется только в том случае, если в заказе присутствуют товары, требующие
доставки. Присылается после того, как пользователь ввёл адрес доставки и необходимо
вычислить возможные способы доставки на введенный адрес и их стоимость. В ответ
возвращаются варианты доставки.

Параметры уведомления:
Имя Тип Примечание
notification_type stringравен "calculate-shipping-cost"
order_id int идентификатор заказа в платёжной систем
идентификатор желания, передается только для сервиса
wish_id int Список желаний, уникален для конкретного пользователя
(user_id, см. ниже)
merchant_id int идентификатор продавца
поля, переданные продавцом при создании заказа (только для
custom_1...N string
сервиса Оплата товаров)
sig string подпись уведомления (см. Формирование подписи)
Параметры позиций заказа, переданные продавцом
item_id_1...N string идентификатор позиции
item_price_1...N stringстоимость
item_quantity_1...N stringколичество
item_currency_1...N stringчисловой код валюты в формате ISO 4217
item_currency_str_1..Nstringстроковый код валюты в формате ISO 4217
Дополнительные параметры уведомления
shipping_country stringстрана адреса доставки в формате ISO 3166-1 alpha-2
почтовый индекс адреса доставки. Эталонный справочник
shipping_code string
индексов доступен на сайте почты России.
локаль пользователя для перевода названий вариантов
locale string доставки, если у продавца нет перевода на язык переданной
локали, необходимо вернуть названия на языке магазина.
Информация о пользователе
user_id int id пользователя ВКонтакте, совершающего оплату
shipping_email stringконтактный e-mail

Формат ответа:
<?xml version="1.0" encoding="UTF-8" ?>
<shipping-methods>
<тип-доставки id="идентификатор варианта" name="имя варианта">
<price currency="код валюты">стоимость доставки</price>
</тип-доставки>
...
</shipping-methods>

Внимание! В случае отсутствия возможности доставить товар по адресу с указанным

индексом необходимо вернуть пустой список способов доставки:
<?xml version="1.0" encoding="UTF-8" ?>
<shipping-methods>

8
</shipping-methods>

Не нужно возвращать ошибку (<failure>).

Параметры ответа:

Имя Тип Примечание

один из трех вариантов:

 "flat-rate" (фиксированная стоимость/единый тариф)

тип доставки string
 "pickup" (самовывоз)
 "merchant-calculated" (все остальные тарифы)

идентификатор способа доставки, будет передан с заказом в

идентификатор
string уведомлениях Проверка параметров заказа и Изменение статуса
варианта
заказа.
имя варианта stringназвание варианта доставки
код валюты stringчисловой или строковый код валюты в формате ISO 4217
стоимость
stringстоимость доставки в указанной валюте
доставки

В случае сервиса Список желаний в момент начала оформления заказа (до получения
способов и стоимости доставки и до изменения состояния заказа) посылается уведомление
проверки наличия и стоимости товара, и только при наличии товара продолжается
оформление заказа.

9
Обработка платежных ошибок
При возникновении критической ошибки обработка заказа прерывается. Если
использовался сервис Оплата товаров, то окно оплаты закрывается и пользователь
перенаправляется на страницу магазина fail_url, переданный при открытии окна оплаты
(см. Создание платежной формы), методом GET, при этом передаются все custom-
параметры заказа (custom_0, custom_1, и т.д.), code - код ошибки, а также params -
значение поля error-parameters, если ошибка была получена в ответ на уведомление (см.
Обработка платежных уведомлений).

Коды ошибки больше 1000 не передаются магазином в ответ на уведомление, а возникают

в результате других ошибочных ситуаций.

Таблица кодов ошибок

Код
Критичность Значение
ошибки
1 true/false общая ошибка
2 false временная ошибка базы данных
10 true несовпадение вычисленной и переданной подписи
параметры запроса не соответствуют спецификации;
11 true в запросе нет необходимых полей;
другие ошибки целостности запроса.
20 true товара не существует
21 true покупателя не существует
22 true некорректная сумма заказа
23 true некорректный метод доставки
24 true товара нет в наличии
ошибки с номерами 100-999 задаются продавцом, при возврате
100-999 таких ошибок обязательно должно присутствовать текстовое
описание ошибки
не удалось разобрать ответ на уведомление; означает, что ответ на
1001
уведомление не соответствует спецификации.
1002 true неизвестная ошибка
в параметре merchant_id передан идентификатор
1003 true
несуществующего магазина.
попытка работать в рабочем (не тестовом) режиме для не
1004 true включенного магазина; необходимо передавать параметр testmode:
1.
1005 true в параметре success_url передан некорректный адрес.
в массиве позиций заказа items было некорректное число позиций -
1006 true
0 или больше 100.
в заказе присутствуют товары, требующие доставки (не
цифровые), в то время как в магазине не предусмотрен выбор
1007 true метода доставки (в графе "Варианты доставки:" выбран вариант
"Нет", который возможен для магазинов, продающих только
цифровые товары).
в заказе присутствуют товары, требующие доставки (не
цифровые), в то время как в магазине указано, что варианты
1008 true доставки заданы вручную (в графе "Варианты доставки:" выбран
вариант "Задать вручную"), однако не задано варианта ни для
одной страны.

10
1101- для позиции N передан некорректный идентификатор товара,
true
1200 где N - это код ошибки минус 1100.
1201- для позиции N передано некорректное название товара,
true
1300 где N - это код ошибки минус 1200.
1301- для позиции N передана некорректная валюта,
true
1400 где N - это код ошибки минус 1300.
1401- для позиции N передана некорректная цена,
true
1500 где N - это код ошибки минус 1400.
1501- для позиции N передано некорректное количество товаров,
true
1600 где N - это код ошибки минус 1500.

Ошибка с кодом 1001 в рабочем режиме магазина первые три раза (на текущее
уведомление текущего заказа) воспринимается не как критическая и уведомление
пересылается повторно. Трехкратная невозможность разбора ответа воспринимается как
критическая ошибка. В тестовом режиме она всегда будет критической. (см. Тестовый
режим).

11
Изменение статуса заказа
Присылается в момент изменения статуса заказа.

Внимание! В случае получения повторного уведомления типа Изменения статуса заказа

(с тем же order_id) ответ должен в точности повторять ответ для исходного уведомления.

К примеру, если было послано это уведомление, и был дан утвердительный ответ, но он
не дошел до сервера ВКонтакте, или по каким-то временным причинам не удалось
перевести заблокированные средства на счет магазина сразу после получения ответа,
такое же уведомление будет послано повторно. При этом не нужно выполнять новый
заказ, нужно просто прислать тот же ответ, что и в предыдущий раз (сохранив у себя
order_id и проверив по нему, что такое уведомление уже приходило).

Параметры уведомления:
Имя Тип Примечание
notification_type string равен "order-state-change"
order_id int идентификатор заказа в платёжной систем
идентификатор желания, передается только для сервиса
wish_id int Список желаний, уникален для конкретного пользователя
(user_id, см. ниже)
merchant_id int идентификатор продавца
поля, переданные продавцом при создании заказа (только для
custom_1...N string
сервиса Оплата товаров)
sig string подпись уведомления (см. Формирование подписи)
Параметры позиций заказа, переданные продавцом
item_id_1...N string идентификатор позиции
item_price_1...N string стоимость
item_quantity_1...N string количество
item_currency_1...N string числовой код валюты в формате ISO 4217
item_currency_str_1..Nstring строковый код валюты в формате ISO 4217
Дополнительные параметры уведомления
новый статус заказа
new_state string
chargeable - готов к оплате
currency int числовой код валюты заказа в формате ISO 4217
currency_str string строковый код валюты заказа в формате ISO 4217
amount doubleсумма заказа
order_date string дата изменения статуса заказа в формате ISO 8601
Информация о пользователе
user_id int id пользователя ВКонтакте, совершающего оплату
user_name string имя пользователя, совершающего оплату
shipping_email string контактный e-mail
Поля информации о доставке
идентификатор варианта доставки, переданный продавцом в
shipping_method string уведомлении Запрос на вычисление способов и стоимости
доставки.
shipping_country string страна в формате ISO 3166-1 alpha-2
shipping_country_str string название страны
shipping_code string почтовый индекс
shipping_city string название города
12
shipping_street string название улицы
shipping_house string номер дома
shipping_flat string номер квартиры
shipping_phone string номер телефона
recipient_name string имя получателя
order_comment string комментарий к заказу
Добавочные поля
телефон получателя; присылается лишь в том случае, если
поле recipient_phone было указано в списке дополнительных
recipient_phone string
полей required_fields (только для сервиса Оплата товаров,
см. Создание платежной формы).

Поля информации о доставке не присылаются, если заказ цифрового типа - см.

 Создание платежной формы для сервиса Оплата товаров.

 Создание формы добавления для сервиса Список желаний.

Значения статусов:
Значение Описание
заказ готов к оплате; платёжная система готова зачислить сумму заказа на счёт
chargeable продавца в случае ответа об успехе, продавец может приступать к отгрузке
заказа; если в ответ будет получено сообщение об ошибке, заказ отменяется.

Формат ответа:
<?xml version="1.0" encoding="UTF-8" ?>
<success>
<order-id>идентификатор заказа в платёжной системе</order-id>
<merchant-order-id>идентификатор заказа в системе продавца</merchant-order-
id>
</success>

Параметры ответа:
Имя
идентификатор заказа в
платёжной системе
идентификатор заказа в
системе продавца
Тип Примечание
идентификатор заказа в платёжной системе, переданный
int
как параметр уведомления "order_id"
идентификатор сохранённого заказа в нумерации
string
продавца; должен быть уникальным для каждого заказа.

13