Вxодящие уведомления
Основы
Важно! Feennex временно отправляет уведомления в формате raw data вместо JSON.
Пример уведомления в raw data
"client_price=1.0
&created=2024-12-03+14%3A39%3A02
&email=1%401.1
&lang=en
&payment_id=1
&payway=bank_usd
&processed=2024-12-03+15%3A47%3A07
&ps_currency=643
&ps_data=%7B%22
amount%22%3A+1.0%2C
+%22bank%22%3A
+%22bank_example%22%2C
+%22card%22%3A+%22%22%2C
+%22card_holder_name%22%3A+null%2C
+%22currency%22%3A+%22usd%22%2C
+%22expired%22%3A+1733226844.041605%2C
+%22method%22%3A
+%22bank_usd%22%2C
+%22paysystem_payway_id%22%3A+%2235%22%2C
+%22phone%22%3A+null%2C
+%22qr_data%22%3A+null%2C
+%22receipt_status_url%22%3A+%22https%3A%2F%2Fexample.com%2C
+%22receipt_url%22%3A+%22https%3A%2F%2Fexample.com%2C
+%22receipt_web%22%3A+%22https%3A%2F%2Fexample.com%2C
+%22rejected_reason%22%3A+%22%22%7D
&shop_amount=1.0
&shop_currency=840
&shop_id=1
&shop_order_id=1
&shop_refund=1.0
&sign=daf8f354f3
&status=success
&user_ip=1.2.3.4"
Вы можете подключить уведомления (callback) о событиях с платежом. Эти уведомления помогают узнать, когда статус платежа меняется.
Пример: Feennex может обрабатывать платеж несколько минут. Если вы подключили уведомления, вам не придется всё это время отправлять запросы на получение информации о платеже. Просто дождитесь уведомления от Feennex.
События, при которых Feennex присылает уведомление, зависят от типа операции:
- Оплата кошельком Feennex
- Оплата сторонними способами оплаты
Обратите внимание! Feennex не присылает уведомления о смене статуса выплаты. Вам нужно периодически запрашивать статус выплаты самостоятельно. Коллбэки на вводе приходят только на финальные статусы
Оплата кошельком Feennex
Если вы создали платеж для приема оплаты с кошельков Feennex (bill), вы будете получать уведомления о следующих событиях:
- Платеж перешел в статус
Paid - Платеж перешел в статус
Canceled
Подробнее про статусы платежей
Платеж при оплате сторонними способами оплаты
Если вы создали платеж для приема оплаты с помощью сторонних способов оплаты (invoice), вы будете получать уведомления о следующих событиях:
- Платеж перешел в статус
Paid - Платеж перешел в статус
Recalculated
Подробнее про статусы платежей
В обоих случаях Feennex отправляет уведомление на URL-адрес для успешной оплаты.
Подключение yведомлений
Вам нужно настроить URL-адреса для отправки уведомлений об успехе и неудаче. Это можно сделать двумя способами:
- Задать URL-адреса в личном кабинете при создании магазина (рекомендуется)
- Передавать URL-адреса в запросе на создание платежа. Требования к URL-адресу — протокол HTTPS и TCP-порт 443.
Обратите внимание! Если вы одновременно задали URL-адреса в личном кабинете и передали в запросе, уведомления будут отправляться на адреса из личного кабинета. Чтобы уведомления приходили на адреса, переданные в запросе, удалите адреса для отправки уведомлений из личного кабинета.
Испoльзование
Когда произошло одно из событий, Feennex присылает уведомление на URL-адрес, который вы передали в запросе или указали в настройках личного кабинета.
Это уведомление содержит объект платежа в актуальном
статусе. Например, если платеж изменил статус на success, в уведомлении вернется
объект этого платежа в статусе success. Полученное уведомление вам нужно проверить на подлинность.
Пpоверка подлинности уведомлений
Когда получите уведомление, проверьте его подлинность с помощью проверки IP-адреса и подписи.
Шаг 1. Проверка IP-адреса
Проверьте IP-адрес, с которого пришло уведомление. Feennex может присылать уведомления со следующих IP-адресов:
63.177.198.141/3218.195.222.85/323.69.209.74/32
Шаг 2. Проверка подписи
Вам нужно сформировать подпись из параметров, которые пришли в уведомлении.
Подпись формируется как при отправке запросов, но в формировании подписи участвуют все параметры,
чьи значения не являются пустой строкой и null.
Пример строки для генерации подписи
5.0:2024-10-30 12:27:48:ru:107120419:card_eur:2024-10-30 12:28:47:978:{"ps_payer_account": "537541XXXXXX7424"}:5.0:978:2104:test_invoice:4.8:successYourSecretKey
После того, как вы сгенерируете подпись, сверьте ее с подписью из уведомления. Если подписи совпадают – уведомление подлинное.
Вы можете менять статус платежа в вашей системе на тот статус, который пришел в уведомлении.
Oтвeт на уведомление
Вам нужно подтвердить, что вы получили уведомление.
Для этого ответьте кодом состояния HTTP 200 и телом сообщения ОК.
Если не подтвердить, что уведомление получено, Feennex будет отправлять его в течение суток с увеличивающимися интервалами.
Примeры уведомлений
Важно! Feennex временно отправляет входящие уведомления (callback) в формате raw data вместо JSON.
Уведомления при успехе
Пример уведомления по успешному платежу при оплате банковской картой
{
"client_price": 2500,
"created": "2024-01-19 15:38:59",
"description": null,
"payment_id": 132803748,
"payway": "bank_usd",
"processed": "2024-01-19 15:39:17",
"ps_currency": 840,
"ps_data": "{\"paymentPayerCode\": \"410014233707050\", \"ps_payer_account\": \"410014233707050\"}",
"shop_amount": 2500,
"shop_currency": 840,
"shop_id": 112,
"shop_order_id": "2750",
"shop_refund": 2300,
"sign": "490001f775c752c",
"status": "success",
}
Пример уведомления по успешному платежа при оплате с помощью кошелька Feennex
{
"client_price": 2500,
"created": "2024-01-19 15:38:59",
"description": null,
"payment_id": 132803748,
"payway": "feennex_usd",
"processed": "2024-01-19 15:39:17",
"ps_currency": 840,
"ps_data": {"ps_payer_account": "2004233707050"},
"shop_amount": 2500,
"shop_currency": 840,
"shop_id": 112,
"shop_order_id": "2750",
"shop_refund": 2300,
"sign": "490001f775c752c",
"status": "success"
}
Уведомления при неудаче
При получении уведомления по отклоненному платежу добавляется причина отказа в параметре rejected_reason.
Пример уведомления по неуспешному платежу при оплате любыми способами, кроме кошелька
{
"client_price": 1500,
"created": "2024-10-23 15:26:36",
"description": null,
"payment_id": 123166089,
"payway": "card_usd",
"processed": "2024-10-23 15:26:41",
"ps_currency": 840,
"ps_data": "{\"ps_payer_account\": \"533669XXXXXX8888\", \"rejected_reason\": \"Na schete karty nedostatochno sredstv dlja vypolnenija operatsii\"}",
"shop_amount": 1500,
"shop_currency": 840,
"shop_id": 112,
"shop_order_id": "37962464",
"shop_refund": 1440,
"sign": "3f00f3b370ffce",
"status": "rejected"
}
Параметры уведомления
| Параметр | Описание |
|---|---|
client_price | Сумма, которую перечислил плательщик. Обязательный |
created | Дата и время создания платежа. Обязательный |
processed | Дата и время изменения статуса платежа (оплата или отклонение). Обязательный |
description | Описание платежа. Обязательный |
payment_id | Уникальный идентификатор платежа в Feennex. Обязательный |
payway | Платежное направление в Feennex, через которое плательщик проводит оплату. Обязательный |
ps_currency | Валюта платежного направления, через которое плательщик проводит оплату. Обязательный |
ps_data | Дополнительная информация от платежной системы, например аккаунт плательщика. Обязательный |
shop_amount | Сумма платежа. Обязательный |
shop_currency | Валюта платежа. Обязательный |
shop_id | Уникальный идентификатор вашего магазина. Обязательный |
shop_order_id | Идентификатор заказа на вашей стороне. Обязательный |
shop_original_amount | Сумма платежа. Параметр содержится в уведомлении, если плательщик оплатил не ту сумму. Фактическая сумма платежа содержится в параметре client_price. Подробнее про действия при неверной сумме платежа |
shop_refund | Сумма зачисления на баланс магазина. Обязательный |
status | Статус платежа. Обязательный. Возможные значения: success – оплачен и зачислен. rejected – отклонен клиентом или платежной системой. Recalculated – сумма по оплате счета была пересчитана. Подробнее о статусах |
sign | Подпись. Обязательный |
Любой параметр | Могут возвращаться любые вспомогательные параметры, которые необходимы для платежа |