Початок роботи з API

Підключення

Перед початком інтеграції вам потрібно виконати кілька кроків:

Створити акаунт і магазин Feennex
Підтвердити магазин
Отримати секретний ключ і налаштувати дозволені IP-адреси
Налаштувати формування підпису у вашій системі
Проінтегруватися з Feennex по API

Створення акаунта і магазину Feennex

Створення акаунта Feennex

Якщо у вас немає акаунта Feennex, зареєструйте його і пройдіть верифікацію.
Тепер можна приступати до створення магазину.

Створення магазину Feennex

Створіть новий магазин. Від імені цього магазину ви будете надсилати запити в Feennex.
Вкажіть назву вашого магазину та його URL-адресу. Натисніть Створити магазин.

Після створення з’явиться сторінка підтвердження магазину.

Підтвердження магазину

Зверніть увагу! Цей крок можна виконати пізніше. Для цього натисніть Пропустити.
Підтвердити магазин можна буде в особистому кабінеті в розділі Магазини.

Щоб надіслати запит на активацію магазину та підключення методів оплати, необхідно пройти верифікацію домену.

Завантажте спеціальний файл і розмістіть його в корені вашого сайту на сервері або хостингу.
Файл має бути доступним для завантаження. Приклад: http://yourwebsite.com/fnx_0123.txt. Натисніть Підтвердити

Якщо все пройшло успішно — сайт відправлено на перевірку. Для уточнення деталей ви можете звернутися в підтримку.

Якщо файл був доданий некоректно, або налаштування на сервері чи хостингу не дозволяють завантажити файл за посиланням,
ви побачите сповіщення На жаль, ми не змогли підтвердити Ваш магазин.
Виконайте рекомендації зі сповіщення або зв’яжіться зі службою підтримки.

Якщо перевірка пройшла, відкриється сторінка налаштувань створеного магазину.
На цій сторінці ви можете керувати створеним магазином:

Змінювати параметри та налаштування, необхідні для платежів і виплат
Переглядати доступні методи прийому платежів і виплат
Керувати налаштуваннями безпеки

Налаштування магазину Feennex

На сторінці налаштувань створеного магазину заповніть поля введення:

URL сповіщень – URL-адреса, на яку Feennex надсилає сповіщення про успішну оплату
URL rejected сповіщень – URL-адреса, на яку Feennex надсилає сповіщення про відхилену оплату
Success URL – URL-адреса, на яку Feennex перенаправить платника після успішної оплати
Failed URL – URL-адреса, на яку Feennex перенаправить платника після неуспішної оплати

Поставте відмітку навпроти пункту Перевіряти унікальність платежів при створенні рахунку. Якщо відмітка проставлена, номер замовлення на вашому боці (параметр shop_order_id) має бути унікальним для кожного платежу.

Feennex присвоює вашому магазину унікальний ідентифікатор shop_id. Він знадобиться при проведенні виплат.

Налаштування безпеки

Розділ Безпека в особистому кабінеті містить налаштування вашого секретного ключа та список дозволених IP-адрес.

Секретний ключ

Секретний ключ ви можете згенерувати в особистому кабінеті або вказати свій власний.

Якщо ви хочете використовувати власний секретний ключ, переконайтеся, що він відповідає таким критеріям:

має довжину не менше 8 символів
містить хоча б одну цифру
містить малі та великі літери

Нікому не передавайте секретний ключ вашого магазину. Цим ключем ви підтверджуєте, що операції проводяться від вашого імені.

Дозволені IP-адреси

У розділі IP-адреси вам потрібно у полі введення вказати IP-адресу, з якої ви будете надсилати запити в Feennex. Після цього натисніть на кнопку + (плюс).

Якщо IP-адрес кілька, ви можете додати їх за один раз. Як роздільник використовуйте ; (крапка з комою).

Формування підпису

Для кожного запиту вам потрібно формувати підпис за допомогою вашого секретного
ключа та передавати його в параметрі sign.

Секретний ключ відповідає за безпеку ваших даних.
Зберігайте його у захищеному місці та не публікуйте на сторонніх ресурсах.
Секретний ключ ви можете отримати в особистому кабінеті в налаштуваннях магазину.

Як сформувати підпис

Крок 1. Відсортуйте всі обов’язкові параметри за алфавітом,
приведіть їх до рядкового типу даних і об’єднайте в один
рядок. Як роздільник використовуйте ":" (двокрапку).
У кінець рядка додайте ваш секретний ключ (без знака ":").

Зверніть увагу! Є особливості під час передавання деяких параметрів:

Обов’язковий параметр email включати в рядок не потрібно.
При формуванні підпису в параметрі amount передавайте один знак після крапки, якщо сума ціла або дробова частина кратна 10, наприклад, 12.0.
В інших випадках передавайте два знаки після крапки, наприклад, 12.01

Приклад об’єднання параметрів в один рядок для запиту на створення платежу

{amount}:{currency}:{payway}:{shop_id}:{shop_order_id}{secret_key}

Замість фігурних дужок вставте значення переданих параметрів. Кількість параметрів у вашому запиті може відрізнятися.

Приклад отриманого рядка

12.34:840:bank_usd:5:4126SecretKey01

Крок 2. Розрахуйте SHA256 хеш отриманого рядка.

Приклад HEX-подання підпису

c438896efecd63

Для онлайн перевірки ви можете скористатися онлайн сервісом.

Приклад формування підпису мовою Python

# Обязательные параметры запроса для формирования подписи

secret = 'SecretKey01'   
data_required = {
    'amount': '12.34',
    'currency': '840',
    'payway': 'card_usd',
    'shop_id': '5',
    'shop_order_id': '4126',
}

# Дополнительные параметры запроса. В формировании подписи не участвуют

data_add = {
    'email': '[email protected]',
}

key = ':'.join([data_required[key] for key in sorted(data_required)]) + secret
sign = hashlib.sha256(key.encode()).hexdigest()

Крок 3. Передавайте отримане значення в запиті в параметрі
sign.

Приклад формування підпису для запиту Створення платежу

{
  "currency": "840",
  "sign": "c438896efecd63",
  "payway": "bank_usd",
  "amount": "12.34",
  "shop_id": "5",
  "shop_order_id": 4126,
  "description": "Оплата заказа"
}

Інтеграція з Feennex по API

Після того, як ви виконаєте попередні кроки, можна переходити до інтеграції. Вона залежить від сценарію інтеграції, який ви хочете використовувати.