google analytics

Уведомления о событиях

Уведомления позволяют интернет-сайту взаимодействовать с сервером PayQR, а также реализовывать различные логики использования PayQR. Например, если интернет-сайту нужно, чтобы покупатель выбрал точку самовывоза, откуда ему забирать покупку, то нужно на уровне кнопки активировать атрибут data-pickpoints-required, а на уровне уведомлений отреагировать на уведомление о событии invoice.pickpoints.updating, где в объекте счета на оплату будет передана информация о городе покупателя (наименование страны, региона и города в соответствии с КЛАДР, включая и сам идентификатор города в kladrId). А именно – в ответе PayQR на это уведомление вернуть в том же объекте счета на оплату список всех доступных точек самовывоза интернет-сайта в параметре pickPoints, разбитый на несколько уровней при необходимости. Рекомендуем сразу отфильтровать точки самовывоза по городу покупателя, чтобы не показывать ему лишнее. Покупатель выберет одну из точек самовывоза, которая в дальнейшем будет присутствовать в счете на оплату в уведомлении о событии invoice.order.creating в параметре pickPointsSelected, и интернет-сайт сможет увеличить или уменьшить стоимость всей корзины (заказа), если это требуется, на основе сделанного выбора покупателем. Обращаем внимание, что ответ на уведомление о событии invoice.order.creating – это первая и последняя возможность интернет-сайта изменить какие-либо данные в объекте счета на оплату в процессе покупки. Дальше начнется процесс оплаты и все изменения будут игнорироваться сервером PayQR.

При возникновении новых событий в PayQR по счетам на оплату или при изменении состояний объектов PayQR мы посылаем webhook-уведомления интернет-сайту на URL интернет-сайта, указанный в личном кабинете.

Для успешной обработки webhook-уведомления сервером необходимо отправить ответ со статусом 200. Если интернет-сайт намеренно отказывается от принятия уведомления, то необходимо отправить статус 409 (Conflict). Иначе сервер PayQR продолжит отправлять уведомления по этому событию в течение очень длительного времени. Рекомендуем не реализовывать на уровне ответов на уведомления сервера PayQR какую-то сложную бизнес-логику, кроме технического подтверждения принятия уведомления статусом 200 и отправки запрашиваемых/измененных данных. В противном случае у покупателя возникнет задержка в процессе оплаты, что может негативно сказаться на конверсии. В любом случае в любой момент интернет-сайт может осуществить возврат денежных средств (отмену оплаченного счета на оплату).

Если в ответе на уведомление о событии необходимо предоставить новую информацию в объект счета на оплату (события invoice.deliverycases.updating и invoice.pickpoints.updating) или изменить содержание объекта счета на оплату (событие invoice.order.creating), то достаточно отправить обратно в том же по структуре объекте только его добавляемые/изменяемые значения (или целиком объект с добавленными/измененными значениями, как будет удобнее).
Например, решили применить скидку определенному покупателю и пересчитать итоговую сумму заказа, возвращаем объект только с одним параметром amount, у которого появилось новое значение.

Типы уведомлений

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

Имена уведомлений соответствуют шаблону resource.event. Наша цель состоит в том, чтобы создать систему, которая позволяет легко представить все разнообразие пользовательских сценариев по интеграции с API PayQR и упрощает взаимодействие между системами как в простых, так и в сложных случаях.

Пример объекта invoice.order.creating  

{
  "object": "event",
  "id": "evt_14EccV2eZvKYlo2C2j1B18pF",
  "created": "2015-08-09T18:31:42.201+04:00",
  "type": "invoice.order.creating",
  "data": {
    "id": "inv_14EeCA2eZvKYlo2C8nDrcXdp",
    "object": "invoice",
    "livemode": false,
    ...
    "amount": 19648.44,
    "status": "new",
  }
}

Пример объекта revert.created  

{
  "object": "event",
  "id": "evt_89f049weufijFCECKoF43l93",
  "created": "2015-08-09T18:31:42.201+04:00",
  "type": "revert.created",
  "data": {
    "id": "rvt_T5JTgj544p45gG36g",
    "object": "revert",
    "livemode": false,
    ...
    "amount": 19648.44,
    "status": "new",
  }
}

offer.invoices.creating
описывает счет на оплату
Вызывается в момент, когда покупатель считал код покупки типа "Привязанный" данного получателя денежных средств.
invoice.deliverycases.updating
описывает счет на оплату
Вызывается в момент, когда в приложение покупателя необходимо передать данные о методах доставки.
invoice.pickpoints.updating
описывает счет на оплату
Вызывается, когда в приложение покупателя необходимо передать данные о точках самовывоза.
invoice.order.creating
описывает счет на оплату

Вызывается, когда проверяется финальная проверка заказа пользователя. На этом этапе необходимо заполнить ИД заказа orderId из созданного на данном этапе заказа в учетной системе магазина.
Заполнение ИД заказа в магазине требуется перед проведением процесса оплаты: аналог номера покупки на чеке. Без заполнения магазином этого поля пользователь не сможет совершить оплату.
Если вы не формируете номер у себя, мы можете вернуть любое значение, например, default, 0.

invoice.paid
описывает счет на оплату
Вызывается, когда система попыталась провести оплату, и оплата прошла успешно.
invoice.failed
описывает счет на оплату

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

invoice.cancelled
описывает счет на оплату

Вызывается, когда магазин отменил счет: например, товара нет на складе.
Также счет может быть отменен системой, если он не был оплачен в отведенный магазином срок.

invoice.reverted
описывает счет на оплату
Вызывается, когда была проведена полная отмена по счету.
receipt.paid
описывает квитанцию
Вызывается, когда квитанция была оплачена.
revert.succeeded
описывает возврат платежа
Вызывается, когда возврат оплаты прошел успешно. Возвращаемая сумма переведена пользователю.
revert.failed
описывает возврат платежа
Вызывается, когда возврат оплаты выдал ошибку.Возвращаемая сумма разблокирована на счете магазина.