API продавца

Для получения платёжных уведомлений на свой Callback URL и возврата средств пользователю вам необходимо использовать API продавца. Формат данных и синтаксис запросов отличаются от API ВКонтакте. Для взаимодействия с этим API вам нужно использовать идентификатор и приватный ключ продавца, полученные вами при заключении договора с платёжной системой. Запросы, ответы и уведомления в API продавца всегда содержат три поля на верхнем уровне, закодированные urlencoded:

• •

  version (string) — версия API.

• •

  data (string) — JSON с данными в кодировке base64.

• •

  signature string — подпись данных. Принцип формирования подписи зависит от конкретного запроса или ответа.

Например:

Можно представить эти данные в формате JSON:

Внутри JSON, закодированного в data, в свою очередь, всегда содержатся два поля:

header (object) — обязательный заголовок. Содержит поля:

• •

  client_id (string)— идентификатор продавца в платёжной системе (то же самое, что и merchant_id);

• •

  ts (integer) — время формирования в Unixtime;

• •

  status (string)— статус ответа (OK или ERROR);

• •

  error (object) — данные об ошибке (опционально).

body (object) — полезная нагрузка. Синтаксис зависит от запроса.

Серверное платёжное уведомление

Уведомление отправляется по факту совершения платежа в пользу продавца на callback URL, который вы указали при заключении договора с платёжной системой, или по факту списания средств с расчётного счёта продавца (например, при возврате). При необходимости вы можете задать несколько адресов. Уведомление будет отправлено и в случае возврата платежа с кэшбеком. Сначала с пользователя спишется сумма кэшбека. Эта сумма будет зачислена на счет мерчанта и ДМР отправит уведомление об отмене кэшбека. И после произойдет возврат средств пользователю по указанной транзакции. Пример уведомления о возврате кэшбека. На уведомление нужно ответить — иначе мы продолжим присылать его снова и снова, предполагая, что продавец не обработал платёж. Если во время обработки уведомления произошла ошибка, нужно вернуть её в ответе — смотрите описание возможных ошибок в разделе Ошибки обработки уведомлений.

Уведомления будут отправляться из подсетей:

• •
  95.213.29.0/24, 93.186.229.0/25 — для тестовых мерчантов
• •
  188.93.57.0/26, 188.93.57.192/26 — для боевых

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

Рекомендуется организовать хранение уведомлений на стороне Service Backend. Это может потребоваться для проведения возвратов по неуспешным транзакциям или для аналитики.

Пример body для уведомления

Пример body для ответа на уведомление

Описание полей body для уведомления

• •
  transaction_id — идентификатор транзакции. Это поле (с тем же значением) необходимо передавать в ответе на уведомление.
• •
  notify_type — тип платёжного уведомления (всегда содержит "TRANSACTION_STATUS"). Это поле (с тем же значением) необходимо передавать в ответе на уведомление.
• •
  amount — сумма платежа. Сумма может быть отрицательной (например, при возврате средств покупателю).
• •
  status — статус транзакции:

  • •
    PAID — для обычных платежей;
  • •
    HOLD — для двухстадийных платежей.
• •
  added — время создания транзакции.
• •
  paid — время завершения транзакции.
• •
  currency — валюта платежа (всегда содержит RUB).
• •
  payee_amount — сумма зачисленных средств за вычетом комиссии платёжной системы.
• •
  pay_method — платёжный метод (всегда содержит internal_out).
• •
  merchant_id — идентификатор продавца.
• •
  merchant_name — мазвание продавца.
• •
  description — комментарий к платежу.
• •
  merchant_param — данные продавца (содержимое поля data из параметров платёжного окна).
• •
  payment_info — данные об участниках платежа:

  • •
    recipient — получатель. Содержит поле client_id с идентификатором продавца в платёжной системе.
  • •
    sender— отправитель. Содержит поле user_id с идентификатором пользователя ВКонтакте.
• •
  issuer_id — идентификатор транзакции в платёжной системе.
• •
  keep_uniq — служебный параметр.
• •
  pay_system_name — наименование платёжного метода.

Проверка подписи уведомления

Подпись платёжного уведомления (поле signature) это строка в base64 — RSA-SHA1-хэш поля data.

Для проверки подписи необходимо использовать публичный ключ платёжной системы:

Пример проверки подписи уведомления на PHP:

Подпись ответа на платёжное уведомление

Подпись ответа платёжного уведомления (поле signature) это строка в base64 — SHA1-хэш в HEX-представлении от конкатенации поля data и приватного ключа продавца.

Формирование подписи ответа на уведомление:

Шаг 1. Собираем data — JSON-объект с заголовком и телом запроса:

Шаг 2. Берём от него base64:

Шаг 3. Конкатенируем с приватным ключом продавца:

Шаг 4. Берём от полученной конкатенации SHA-1 хэш в HEX:

Конечный результат:

Ошибки обработки уведомлений

Если при обработке уведомления произошла ошибка, необходимо вернуть данные о ней в ответе на уведомление:

Возможные значения error_code:

• •
  ERR_SYSTEM — техническая ошибка на стороне продавца. Уведомление будет отправлено повторно;
• •
  ERR_ARGUMENTS — ошибка обработки параметров уведомления. Уведомления будут приостановлены;
• •
  ERR_SIGNATURE — ошибка проверки подписи уведомления. Уведомления будут приостановлены;
• •
  ERR_DUPLICATE — уведомление с указанным transaction_id уже обработано. Уведомления будут остановлены.

Возврат средств покупателю

Возврат средств может быть осуществлен в день платежа до 23:00 по московскому времени (отмена) или в любой другой день (возврат). Разница в запросах на отмену и возврат заключается в эндпоинте для отправки запроса к API. /vkpay/reverse в отличие от /transaction/refund возвращает средства пользователью полностью, вместе с комиссией ДМР, если возврат средств был осуществлен в день платежа до 23:00 по московскому времени. В другом случае, если возврат средств был осуществлен на следующий день или после 23:00, результат работы метода аналогичен полному возврату методом /transaction/refund.

Для отмены покупки до 23:00 этого же дня нужно отправить запрос по следующему URL: https://api.money.mail.ru/money/2-04/vkpay/reverse.

Важно! Частичный возврат с методом /vkpay/reverse невозможен.

Для полного или частичного возврата средств спустя 23 часа после платежа нужно отправить запрос к API продавца по следующему URL: https://api.money.mail.ru/money/2-04/transaction/refund.

Пример запроса (curl)

Пример body для запроса на возврат/отмену средств

Описание полей body для запроса на возврат/отмену средств

• •

  transaction_id (string) — идентификатор транзакции, по которой нужно сделать возврат/отмену.

• •

  amount (string) — сумма возврата/отмены. По умолчанию — полная сумма транзакции (только для /transaction/refund).

• •

  currency (string) — валюта платежа (всегда содержит RUB) (только для /transaction/refund).

• •

  reason (string) — причина возврата/отмены.

Пример body для ответа на запрос возврата/отмены средств

Описание полей body для ответа на запрос возврата/отмены средств

• •

  transaction_id (string) — идентификатор транзакции возврата/отмены.

• •

  action (string) — действия для продолжения. Содержит одно из значений:

  • •
    wait — необходимо запросить статус транзакции запросом transaction/status;
  • •
    stop — статус транзакции конечный и содержится в action_param.
• •

  action_param (object) — набор параметров для action (значение может быть пустым). status — дополнительное уточнение статуса. Для action=stop возможные значения status: success, fail

Подпись запроса на возврат/отмену средств

Подпись запроса формируется аналогично подписи ответа на платёжное уведомление, с единственным отличием — на третьем этапе, при конкатенации data и приватного ключа продавца, в начало строки необходимо добавить относительный URL запроса: /money/2-04/transaction/refund

или

/money/2-04/vkpay/reverse

Возможные ошибки

В ответе на запрос может вернуться одна из следующих ошибок:

• •
  ERR_TRANSACTION_NOT_FOUND — транзакция с переданным идентификатором не найдена.
• •
  ERR_AMOUNT_GREATER_THAN_ALLOWED— сумма возврата/отмены больше суммы платежа.
• •
  ERR_ALREADY_REFUNDED — платеж уже полностью возвращён.
• •
  ERR_REFUND_FAILED — возврат/отмена не удались.
• •
  ERR_NOMONEY — на счёте продавца недостаточно средств для возврата.
• •
  ERR_ACCESS_DENIED — нет доступа к указанной транзакции.
• •
  ERR_RATE_LIMIT — превышено максимально допустимое число возвратов/отмен по одной транзакции.
• •
  ERR_COMMON — возможно, ошибка в названии signature.

Статус транзакции

В случае, если запрос на возврат средств поле action имеет значение wait, вам следует «поллить» статус транзакции. https://api.money.mail.ru/money/2-04/transaction/status.

Пример запроса (curl)

Пример body для запроса

Описание полей body для запроса статуса транзакции

• •
  transaction_id (string) — идентификатор транзакции возврата.

Пример body для ответа на запрос статуса транзакции

Описание полей body для ответа на запрос статуса транзакции

• •

  transaction_id (string) — идентификатор транзакции возврата.

• •

  action (string) — действия для продолжения. Содержит одно из значений:

  • •
    wait — необходимо запросить статус транзакции запросом transaction/status;
  • •
    stop — статус транзакции конечный и содержится в action_param.
• •

  action_param (object) — набор параметров для action (значение может быть пустым). status — дополнительное уточнение статуса. Для action=stop возможные значения status: success, fail

Подпись запроса на статус транзакции

Подпись запроса формируется аналогично подписи ответа на платёжное уведомление, с единственным отличием — на третьем этапе, при конкатенации data и приватного ключа продавца, в начало строки необходимо добавить относительный URI запроса: /money/2-04/transaction/status

Возможные ошибки

• •
  ERR_NOT_FOUND — запрошенная транзакция не найдена

Тестирование работы с платежами

Для тестирования API платежной формы и API продавца мы предоставим вам данные тестового продавца — идентификатор продавца, приватный ключ продавца и публичный ключ платёжной системы. Для начала работы вам нужно создать приложение ВКонтакте и сообщить нам адрес callback URL для отправки серверных платёжных уведомлений. Напоминаем, что для корректной работы с логикой сообщений сообщества в период тестирования необходимо разрешать доступ к отправке сообщений пользователю. После размещения в каталоге это будет происходить автоматически.

К сожалению, мы не предоставляем кошельки для тестирования. Платежи в адрес тестовых продавцов автоматически возвращаются получателям в течение суток. Мы рекомендуем использовать для тестирования небольшие значения amount — например, 1 рубль.

Важно! У тестового продавца нет логотипа и названия в платёжной системе, поэтому вы не увидите их в платёжном окне. После заключения договора при переходе на боевые данные, будут использованы указанные вами логотип и название продавца.

Пользователь не может совершить платеж в пользу тестового продавца с 23.00 до 0.30. Это ограничение связано с возвратами тестовых платежей.

В течение этого времени можно поднять платежное окно, но произвести оплату нельзя.