В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-адресу для успішної оплати.
Підключення сповіщень
Вам потрібно налаштувати URL-адреси для надсилання сповіщень про успіх та невдачу. Це можна зробити двома способами:
- Задати URL-адреси в особистому кабінеті під час створення магазину (рекомендується)
- Передавати URL-адреси в запиті на створення платежу.
Вимоги до URL-адреси — протокол HTTPS і TCP-порт 443.
Зверніть увагу! Якщо ви одночасно задали URL-адреси в особистому кабінеті та передали в запиті,
сповіщення надсилатимуться на адреси з особистого кабінету.
Щоб сповіщення приходили на адреси, передані в запиті, видаліть
адреси для надсилання сповіщень з особистого кабінету.
Використання
Коли відбулася одна з подій, Feennex надсилає сповіщення на URL-адресу,
яку ви передали в запиті або вказали в налаштуваннях особистого кабінету.
Це сповіщення містить об’єкт платежу в актуальному
статусі. Наприклад, якщо платіж змінив статус на success, у сповіщенні повернеться
об’єкт цього платежу в статусі success. Отримане сповіщення вам потрібно перевірити на справжність.
Перевірка справжності сповіщень
Коли отримаєте сповіщення, перевірте його справжність за допомогою перевірки IP-адреси та підпису.
Крок 1. Перевірка IP-адреси
Перевірте IP-адресу, з якої прийшло сповіщення. Feennex може надсилати сповіщення з таких IP-адрес:
-
63.177.198.141
Крок 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
Після того як ви згенеруєте підпис, звірте його з підписом зі сповіщення.
Якщо підписи збігаються – сповіщення справжнє.
Ви можете змінювати статус платежу у вашій системі на той статус, який прийшов у сповіщенні.
Відповідь на сповіщення
Вам потрібно підтвердити, що ви отримали сповіщення.
Для цього відповідайте кодом стану HTTP 200 і тілом повідомлення ОК.
Якщо не підтвердити, що сповіщення отримане, Feennex надсилатиме його
протягом доби зі збільшеними інтервалами.
Приклади сповіщень
Важливо! 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 | Підпис. Обов’язковий |
Будь-який параметр | Можуть повертатися будь-які допоміжні параметри, які необхідні для платежу |