Документація API. Повна документація API для роботи з платежами, балансами та транзакціями. Basic URL: https://core.feennex.com/

API Feennex (UA)

Вступ

Feennex — це рішення для електронних платежів, яке дозволяє приймати платежі та здійснювати виплати.

За допомогою Feennex покупці можуть переказувати вам гроші будь-яким із підтримуваних способів. Після оплати Feennex перевіряє успішність зарахування та перераховує вам гроші.

Щоб почати приймати платежі, вам потрібно вибрати найбільш зручний сценарій інтеграції, створити магазин і проінтегруватися з Feennex через API.

Про прийом платежів

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

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

Платник перенаправляється на платіжну сторінку – вашу або готову. На платіжній сторінці платник виконує такі дії:

Обирає спосіб оплати
Вводить дані для оплати
За потреби підтверджує платіж. Наприклад, проходить автентифікацію за 3-D Secure

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

Доступні способи оплати для вашого магазину ви можете дізнатися в особистому кабінеті у налаштуваннях магазину в розділі Методи оплати. Для підключення додаткових способів оплати зв’яжіться з менеджером.

Про виплати

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

Доступні платіжні системи для вашого магазину ви можете дізнатися в особистому кабінеті у налаштуваннях магазину в розділі Напрямки виводу. Для підключення додаткових способів оплати зв’яжіться з менеджером.

Формaт взаємодії

У Feennex API є кілька основних сутностей:

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

Процес оплати залежить від обраного сценарію інтеграції

Основи

Feennex API побудоване на принципах REST. Кожен запит в API пов’язаний із виконанням певної дії над платежем або виплатою, наприклад створення чи отримання статусу.

Feennex API використовує HTTP, що робить його сумісним із розробкою будь-якою мовою програмування, яка підтримує HTTP-бібліотеки (наприклад, Requests, Httpx, Axios, Guzzle та інші).

API endpoint: https://core.feennex.com/<метод API>

API підтримує POST та GET-запити. POST використовує JSON для аргументів, а GET — рядкові запити. API завжди повертає відповідь у форматі JSON, незалежно від типу запиту.

Під час надсилання запиту до Feennex API потрібно вказати заголовок "Content-Type: application/json" і щоразу генерувати підпис за допомогою вашого секретного ключа. Секретний ключ можна отримати в особистому кабінеті.

Якщо ви не передали обов’язкові параметри, у відповіді повернеться помилка з поясненням, якого параметра бракує в запиті.

Для роботи з API Feennex ви можете використовувати готові бібліотеки для мов Python та PHP.

Oбрoбкa відповідей

Feennex API обробляє отриманий запит негайно та повертає результат обробки. Відповідь містить код відповіді HTTP, стандартні заголовки та тіло відповіді у форматі JSON.
У тілі відповіді повертаються такі параметри:

data — містить дані, специфічні для кожного запиту. Тип – object.
error_code — містить код помилки. Тип - number. Приклад: 0 – помилок немає. Докладніше про можливі коди помилок
result — показує, пройшов запит успішно чи ні. Тип – boolean. Приклад: true
message — містить опис помилки. Тип – string. Приклад: "Ok". За значенням цього параметра можна дізнатися, що пішло не так.

Формат відповіді

Тіло відповіді при успіху

Формат тіла відповіді — JSON. Параметри тіла відповіді залежать від запиту.

Приклад тіла відповіді

{
  "data": {
    "data": {
      "session_id": "3067894a580242dd86e03890506a88b"
    },
    "id": 499564464,
    "method": "GET",
    "url": "https://example.com"
  },
  "error_code": 0,
  "message": "Ok",
  "result": true
}

Тіло відповіді при помилці Якщо із запитом щось не так, повернеться тіло відповіді у форматі JSON з кодом помилки. Докладніше про коди помилок Приклад тіла відповіді при неправильно сформованому підписі

{
    "data": null,
    "error_code": 10,
    "message": "Invalid sign, string_to_sign: 500:840:card_usd:6199:99991",
    "result": false
}

В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`	Підпис. Обов’язковий
`Будь-який параметр`	Можуть повертатися будь-які допоміжні параметри, які необхідні для платежу

Початок роботи з 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

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

Вибір сценарію інтеграції

Ви можете інтегруватися за допомогою одного з трьох сценаріїв:

Платіжна сторінка Feennex. Потрібно сформувати HTML-форму та розмістити її у вашому магазині.
Створення платежу (редиректний сценарій). Потрібно надіслати запит на створення платежу та перенаправити платника на сторінку оплати.
Самостійна інтеграція (Host-to-Host).
Необхідно самостійно реалізувати платіжну сторінку, сторінки успішного та неуспішного платежу. Платник здійснюватиме оплату лише у вашому інтерфейсі.

Оберіть відповідний сценарій та повідомте про своє рішення менеджеру.

Сценарій Платіжна сторінка Feennex

Основи

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

Коли користувач натискає кнопку підтвердження, інформація про платіж надсилається у Feennex.

Надсилання форми ініціює на стороні Feennex створення платежу.
Платник перенаправляється на платіжну сторінку Feennex.

На платіжній сторінці платник може вибрати спосіб оплати,
за потреби залишити свої дані та здійснити оплату.

Особливості

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

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

Формування HTML-форми

Для перенаправлення платника на платіжну сторінку Feennex вам необхідно сформувати HTML-форму.

Приклад HTML-форми

form name="Pay" method="post" action=" https://pay.feennex.com/en/pay" accept-charset="UTF-8
input type="hidden" name="amount" value="10.00" 
input type="hidden" name="currency" value="840" 
input type="hidden" name="shop_id" value="1" 
input type="hidden" name="sign" value="2a966c9942652" 
input type="hidden" name="shop_order_id" value="101"   
input type="submit"
input type="hidden" name="description" value="Оплата по заказу №123" 
/form

Параметри платіжної форми

URL-адреса для надсилання форми

Надсилайте форму на https://pay.feennex.com/en/pay. Зверніть увагу, що платіжна сторінка підтримує кілька мов.

Параметри форми

Параметр	Формат	Опис
Обов’язкові параметри
`shop_id`	Integer	Ідентифікатор вашого магазину в системі Feennex. Приклад: 5
`amount`	Number	Сума платежу. Не більше двох знаків після крапки. Приклад: 1.00
`currency`	Number	Валюта платежу. Приклад: 840 Можливі значення валют
`description`	String	Опис платежу. Приклад: Оплата за замовлення №123
`shop_order_id`	String	Номер замовлення на вашому боці. Приклад: h8fj38. Залежно від налаштувань магазину, Feennex може перевіряти унікальність номера замовлення. Не більше 255 символів
`sign`	String	Підпис запиту. У формуванні підпису беруть участь лише обов’язкові параметри
Необов’язкові параметри
`payway`	String	Платіжний напрям, через який проходить оплата. Приклад: card_usd
`payer_account`	String	Email або номер гаманця акаунта платника в Feennex. Приклад: [email protected]" або "201494711279. Якщо ви передали цей параметр, то рахунок зможе оплатити лише вказаний акаунт. Тільки для оплати з гаманця Feennex.
`failed_url`	String	URL-адреса, на яку Feennex перенаправить платника після невдалої оплати рахунку. Приклад: https://feennex.com/failed
`success_url`	String	URL-адреса, на яку Feennex перенаправить платника після успішної оплати рахунку. Приклад: https://feennex.com/success

Сценарій Створення платежу (редиректний)

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

Вам необхідно самостійно реалізувати вибір способу оплати та повідомлення користувачу результатів проведення платежу.

Методи API, які потрібно використовувати, відрізняються залежно від способу оплати.

Приклад реалізації

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

Діаграма проведення платежу при оплаті гаманцем Feennex

Діаграма проведення платежу при оплаті карткою

Важливо! Переконайтеся, що перед початком інтеграції ви виконали всі підготовчі кроки

Для інтеграції по API потрібно створити платіж, отримати посилання на платіжну сторінку та перенаправити на неї платника.

Оплата гаманцем Feennex

Зверніть увагу! Для цього способу оплати вам потрібно використовувати методи для прийому платежів за допомогою гаманця Feennex.
В URL-адресі такі методи мають префікс bill.

Крок 1. Створіть платіж. У запиті передайте суму, валюту, платіжний напрям, ідентифікатор вашого магазину та ідентифікатор замовлення. У параметрі sign передайте підпис запиту.

Приклад запиту

curl https://core.feennex.com/bill/create \
   -H 'Content-Type: application/json' \
   -d '{
          "shop_currency": 840,
          "sign": "66c8d27b887",
          "payway": "feennex_usd",
          "payer_currency": 840,
          "shop_amount": 1000,
          "shop_id": 5,
          "shop_order_id": 4127
       }'

У запиті ви можете додатково передавати URL-адреси ваших сторінок успіху та невдачі для редиректу користувача після оплати, а також URL-адресу, на яку Feennex буде надсилати сповіщення.

Перед передачею URL-адрес переконайтеся, що в особистому кабінеті ви видалили старі адреси, які вказували при створенні магазину – у цих адрес вище пріоритет. Докладніше про налаштування магазину

Крок 2. Перенаправте користувача на url, який повернеться у відповіді в об’єкті data. Це посилання на платіжну сторінку Feennex, на якій користувач введе дані гаманця Feennex і підтвердить платіж.

Приклад відповіді

{
   "data":{
      "created": "Tue, 20 Feb 2024 13:58:35 GMT",
      "id": 123,
      "lifetime": 43200,
      "payer_account": null,
      "payer_currency": 840,
      "payer_price": 1000.0,
      "shop_amount": 1000.0,
      "shop_currency": 840,
      "shop_id": 5,
      "shop_order_id": "4127",
      "shop_refund": 930.0,
      "url": "https://example.com"
   },
   "error_code":0,
   "message":"Ok",
   "result":true
}

Якщо оплата пройшла, Feennex виконує такі дії:

змінює статус платежу на Paid
редиректить платника на сторінку успіху, яку ви передали в запиті або вказували в налаштуваннях вашого магазину в особистому кабінеті
надсилає колбек про успіх на URL-адресу, яку ви передали в запиті або вказували в особистому кабінеті

Якщо щось пішло не так, Feennex виконує такі дії:

змінює статус платежу на Expired або Canceled
редиректить платника на сторінку невдачі, яку ви передали в запиті або вказували в налаштуваннях вашого магазину в особистому кабінеті
надсилає колбек про невдачу на URL-адресу, яку ви передали в запиті або вказували в особистому кабінеті

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

Оплата іншими способами

Зверніть увагу! При оплаті будь-якими способами, окрім гаманця Feennex, вам потрібно використовувати метод Створення платежу.
В URL-адресі, на який потрібно надіслати запит, є префікс invoice.

Крок 1. Створіть платіж. У запиті передайте суму, валюту, платіжний напрям, ідентифікатор
вашого магазину та ідентифікатор замовлення. У параметрі sign передайте підпис запиту.

Приклад запиту

curl https://core.feennex.com/invoice/create \
   -H 'Content-Type: application/json' \
   -d '{
          "currency": 840,
          "sign": "c438896efecd63",
          "payway": "card_usd",
          "email": "[email protected]",
          "amount": 1000,
          "shop_id": 5,
          "shop_order_id": 4126
       }'

Крок 2. Перенаправте користувача на url, який повернеться у відповіді в об’єкті data. Це посилання на сторонню платіжну систему, на якій користувач введе платіжні дані та підтвердить платіж.

Приклад відповіді

{
   "data":{
      "data":{
         "language":"en",
         "mdOrder":"0304a352-12c0-45bf-9ee8-694a2a381bcb"
      },
      "id":497063651,
      "method":"GET",
      "url":"https://payment-link-example.ru"
   },
   "error_code":0,
   "message":"Ok",
   "result":true
}

Якщо оплата пройшла, Feennex виконує наступні дії:

змінює статус платежу на success
перенаправляє платника на сторінку успіху, яку ви передали в запиті або вказали в налаштуваннях вашого магазину в особистому кабінеті
відправляє колбек про успіх на URL-адресу, яку ви вказали в запиті або вказали в особистому кабінеті

Якщо щось пішло не так, Feennex виконує наступні дії:

змінює статус платежу на Rejected або інший статус, який вказує на помилку
перенаправляє платника на сторінку невдачі, яку ви вказали в запиті або в налаштуваннях вашого магазину в особистому кабінеті
відправляє колбек про невдачу на URL-адресу, яку ви вказали в запиті або вказали в особистому кабінеті

Додатково ви можете дізнатися статус платежу при оплаті іншими способами.

Сценарій Самостійна інтеграція Host-to-Host

У цьому сценарії вибір способу оплати та введення даних для оплати відбувається на вашому боці.

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

Вам необхідно самостійно реалізувати наступні кроки процесу оплати:

вибір способу оплати;
отримання від користувача даних для оплати обраним способом;
повідомлення користувачеві результатів проведення платежу.

Процес інтеграції відрізняється залежно від способу оплати.

Оплата банківською карткою

Зверніть увагу! Платежі карткою доступні, якщо для вашого магазину підключений цей спосіб оплати і є сертифікат на відповідність вимогам PCI DSS. Якщо сертифіката немає, виберіть інший сценарій інтеграції.

Для інтеграції по API потрібно виконати 4 кроки:

Створити платіж і отримати ідентифікатор сесії
Отримати токен і URL-адресу
Сформувати HTML-форму
Перенаправити платника на HTML-форму

Крок 1. Створення платежу

Для створення платежу використовуйте метод Створення платежу, але в параметрі payway передавайте значення для сценарію Host-to-Host. Це значення ви можете отримати у менеджера або переглянути в налаштуваннях магазину в особистому кабінеті. Зазвичай воно має префікс h2h. Приклад: bank_h2h_usd.

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

curl https://core.feennex.com/invoice/create \
   -H 'Content-Type: application/json' \
   -d '{
          "currency": "840",
          "sign": "912b985f1895962",
          "payway": "bank_h2h_usd",
          "amount": "1000",
          "shop_id": 112,
          "shop_order_id": 4128
       }

У відповіді в параметрі session_id повернеться ідентифікатор сесії. Збережіть цей ідентифікатор – він знадобиться на наступних кроках.

Приклад відповіді

{
    "data": {
        "data": {
            "session_id": "3067894a580242dd86e03890506a88ba"
        },
        "id": 499564464,
        "method": "GET",
        "url": "https://example.com"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Крок 2. Отримання токена та URL-адреси

Для отримання токена використовуйте метод Дані для HTML-форми. У тілі запиту передайте ідентифікатор сесії, який ви отримали на попередньому кроці в параметрі session_id.

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

curl https://example.com/h2h_data \
   -H 'Content-Type: application/json' \
   -d '{
          "session_id": "3067894a580242dd86e03890506a88ba"
       }

У відповіді повернуться параметри form_token і payform_url. Збережіть їх – вони будуть потрібні на наступному кроці.

Приклад відповіді

{
   "data":{
      "form_token":"uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8",
      "payform_url":"https://example.com/payform/"
   },
   "error_code":0,
   "message":"success",
   "result":true
}

Крок 3. Формування платіжної форми

Вам потрібно зібрати дані банківської картки платника та надіслати запит на створення HTML-форми.

Збір даних банківської картки платника

Зверніть увагу! У вас повинен бути сертифікат на відповідність вимогам PCI DSS

З вашого боку вам потрібно реалізувати сторінку введення даних банківської картки платника. На цій сторінці потрібно зібрати такі дані:

рік і місяць закінчення терміну дії картки
тризначний код CVV або CVC
номер картки
ім'я та прізвище власника картки.

Відправлення запиту на створення HTML-форми

Вам потрібно відправити POST-запит на створення HTML-форми. Запит потрібно відправити на payform_url, який ви отримали на попередньому кроці. У тілі запиту потрібно передати дані банківської картки платника, form_token та ідентифікатор сесії session_id.

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

curl https://example.com/payform/ \
   -H 'Content-Type: application/json' \
   -d '{
          "expiry_year": "26",
          "cvv": "123",
          "expiry_month": "12",
          "card_number": "4111111111111111",
          "card_holder": "IVANOV IVAN",
          "form_token": "uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8",
          "session_id": ""
       }

Крок 4. Перенаправлення платника на HTML-форму

Перенаправте платника на HTML-форму, яку ви отримали у відповіді на попередньому кроці. Платник автоматично перейде на сторінку введення коду 3D-secure. Якщо оплата пройшла, Feennex перенаправить платника на Success URL. Якщо оплата не пройшла або код невірний – на Failed URL.

Оплата переказом на банківський рахунок

Платники зможуть перерахувати оплату на банківський рахунок одним із таких способів:

Номер картки — платник бачить номер картки, на яку потрібно надіслати переказ.

Для інтеграції по API потрібно виконати три кроки:

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

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

Крок 1. Створення платежу

Для створення платежу використовуйте метод Створення платежу, але в параметрі payway передавайте значення для сценарію Host-to-Host. Це значення ви можете отримати у менеджера або переглянути в налаштуваннях магазину в особистому кабінеті. Зазвичай воно має префікс h2h. Приклад: bank_h2h_usd.

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

curl https://core.feennex.com/invoice/create \
   -H 'Content-Type: application/json' \
   -d '{
          "currency": 840,
          "sign": "912b985f1895962",
          "payway": "bank_h2h_usd",
          "amount": 1000,
          "shop_id": 112,
          "shop_order_id": 4128
       }'

Приклад відповіді

{
   "data":{
      "data":{},
      "id":123456789,
      "method":"bank",
      "url":"h2h"
   },
   "error_code":0,
   "message":"Ok",
   "result":true
}

Крок 2. Отримання даних для переказу

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

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

Зверніть увагу! Якщо даних для переказу немає, повторіть запит пізніше – дані для переказу присвоюються платежу не відразу.

Приклад запиту на отримання даних для переказу

curl https://core.feennex.com/invoice/check \
   -H 'Content-Type: application/json' \
   -d '{
          "now": "2024-02-05 18:37:02",
          "sign": "32b2c32caa8ad",
          "shop_id": 112,
          "shop_order_id": 4128
       }'

Feennex повертає стандартну відповідь. В об'єкті ps_data містяться дані для перекладу.

Параметр	Тип	Опис
amount	number	Сума, яку повинен перевести платник
bank	string	Найменування банку отримувача. Значення повертається, якщо параметр method має значення `sbp`. В інших випадках повертається порожнє значення
card	string	Номер банківської картки отримувача. Значення повертається, якщо параметр method має значення `bank`. В інших випадках повертається порожнє значення
card_holder_name	string	ПІБ отримувача
currency	string	Валюта переказу
expired	string	Час, до якого платник повинен відправити переказ. Рекомендується попереджати про це платника
method	string	Код способу оплати. Можливі значення вам повідомить менеджер.
phone	string	номер телефону платника. Значення повертається, якщо параметр method має значення `sbp`. В інших випадках повертається порожнє значення
url	string	УРЛ

Крок 3. Запит статусу платежу

Після відображення даних для переказу ви можете перевіряти статус платежу: періодично надсилати запит або чекати на успішний callback.

Якщо надсилаєте запит, використовуйте Запит статусу платежу при оплаті через сторонні платіжні системи.

У сценарії Host-to-Host статуси працюють так само, як і при створенні рахунку на оплату. Якщо у відповіді в параметрі status повертається значення 4 — платник успішно провів оплату, гроші надійшли на ваш гаманець. Детальніше про статуси рахунку

Приклад успішної відповіді

{
   "data":{
      "client_price": 1000,
      "created": "2024-02-05 18:37:02",
      "description": "Deposit",
      "is_unique": true,
      "payment_id": 123456789,
      "payway": "bank_h2h_usd",
      "processed": null,
      "ps_currency": 840,
      "ps_data": {
         "amount": 1000,
         "bank": "sberbank",
         "card": "",
         "card_holder_name": "Иванов Иван Иванович",
         "currency": "usd",
         "expired": 1707152043.557505,
         "method": "bank",
         "phone": "79999999999",
         "url": ""
      },
      "shop_amount": 1000,
      "shop_currency": 840,
      "shop_id": 50,
      "shop_order_id": "4128",
      "shop_refund": 900,
      "status": 4,
      "updated": "2024-02-05 18:37:18"
   },
   "error_code": 0,
   "message": "Ok",
   "result": true
}

Після оплати

Повернення

Повернення в Feennex залежать від способу оплати. Детальну інформацію вам надасть менеджер.

Неправильна сума оплати

Зверніть увагу. Платник може перерахувати неправильну суму тільки при переказі на банківський рахунок.

Якщо платник перерахував неправильну суму, статус платежу змінюється на recalculated – остаточний і незмінний статус. Feennex надсилає вам повідомлення про зміну статусу платежу на recalculated.

В отриманому повідомленні та при запиті статусу платежу фактична сума, яку переказав платник, повертається в параметрі client_price. Початкова сума платежу – в параметрі shop_original_amount.

Ваші дії відрізняються залежно від того, чи достатньо платник переказав грошей для оплати, чи ні.

Недостатня оплата

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

Переплата

Вам потрібно самостійно домовитися з платником, як ви компенсуєте йому суму переплати.

Платник здійснив оплату переказом на банківський рахунок, але статус не змінюється

Зверніть увагу. Тільки для способу оплати Переказ на банківський рахунок.

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

Ви можете самостійно реалізувати сторінку завантаження чека і надсилати в Feennex по API чек, який завантажив платник, або скористатися готовою формою для надсилання чека.

Крок 1. Реалізація сторінки завантаження чека

Зверніть увагу! Якщо ви не хочете реалізовувати свою сторінку завантаження чека, переходьте до кроку 2.

На сторінці завантаження чека рекомендується попередити платника, що розмір зображення не повинен перевищувати 10 МБ, а на чеку має бути видно таку інформацію:

Час переказу
Відправник і одержувач переказу
Сума переказу

Приклад сторінки для завантаження чеків

Зверніть увагу! Для кожного платежу платник може надіслати тільки один чек. Підтримувані формати: JPEG, JPG, PNG, PDF, WebP, HEIF.

Крок 2. Запит статусу платежу

Для роботи з чеками вам потрібно отримати значення параметра id – воно унікальне для кожного платежу. Щоб отримати значення цього параметра, запитайте статус платежу. У відповіді в об'єкті ps_data повертаються наступні параметри:

receipt_url – URL-адреса для завантаження чека по API
receipt_status_url – URL-адреса для перевірки статусу чека по API
receipt_web – URL-адреса для завантаження чека через форму. На цю адресу вам потрібно перенаправити платника, якщо ви не хочете реалізовувати форму завантаження чека.

Приклад параметра receipt_url

"receipt_url": "https://<baseURL>/api/v1/order/ade32e06-6fa4-425a-9c4c-e026ac6d93e6/receipt"

У цьому параметрі https://baseURL/api/v1/order/ – URL-адреса для відправлення запитів на завантаження чека. Рядок ade32e06-6fa4-425a-9c4c-e026ac6d93e6 – значення параметра id.

Тільки для тих, хто реалізував сторінку завантаження чека (крок 1).

За допомогою методу Відправлення чеків відправляйте в Feennex чек, який завантажив платник. Формувати підпис для цього методу не потрібно.

Адресу для відправлення запиту та значення параметра id ви отримали на кроці 2 в параметрі receipt_url.

Приклад запиту

curl -X POST \ 
--location 'https://<baseURL>/api/v1/order/ade32e06-6fa4-425a-9c4c-e026ac6d93e6/receipt' \
--form 'file=@"/home/cwm/Pictures/receipt.jpg"'

Якщо чек успішно відправлений, повертається відповідь з HTTP-кодом 200.

Приклад успішної відповіді

null

Після відправлення запиту технічна підтримка Feennex обробить переказ.

Щоб переконатися, що переказ пройшов, періодично надсилайте запити на отримання інформації про платіж

Крок 4. Відображення інформації про статус чека

Зверніть увагу! Цей етап можна пропустити.

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

Для отримання статусу чека вам потрібна адреса для відправлення запиту і значення параметра id. Ці значення ви отримали на кроці 2 в параметрі receipt_ status_url.

Приклад запиту

curl -X GET \ 
--location 'https://<baseURL>/api/v1/order/ade32e06-6fa4-425a-9c4c-e026ac6d93e6/receipt/status' \

У відповіді повертається ідентифікатор чека, статус чека і коментар від технічної підтримки Feennex.

Приклад успішної відповіді

[
    {
        "id": "c9e35f42-62de-45c4-8092-152ba47d81e5",
        "status": "pending",
        "comment": null
    }
]

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

Неуспішна оплата

У процесі оплати щось може піти не так. Наприклад, не вдається створити платіж або банк недоступний. Щоб ви могли краще розуміти, що сталося з платежем, Feennex повертає об'єкт платежу з параметром status.

За статусом ви можете визначити стан платежу і використовувати ці дані для аналізу та вирішення проблем, виведення повідомлень платнику та будь-яких інших цілей.

Детальніше про статуси при невдалих переказах

Реєстри

Feennex формує реєстри успішних операцій, за допомогою яких ви можете звіряти розрахунки. До реєстрів входять такі операції:

Прийняті платежі
Проведені виплати
Службові операції

Feennex збирає відомості про всі операції за добу – з 00:00:00 до 23:59:59 за UTC+3. Ви можете запросити формування звіту за один день, тиждень або місяць.

В особистому кабінеті в розділі Історія ви можете самостійно генерувати реєстри для необхідних магазинів.

Якщо ви хочете періодично отримувати реєстри на електронну пошту, підпишіться на їх отримання.

Підписка на розсилку реєстрів

Щоб Feennex надсилав повідомлення на електронну пошту, повідомте менеджеру наступну інформацію:

Електронна пошта одержувачів
Назви магазинів, для яких потрібно розсилати реєстри
Період, за який потрібно формувати реєстр – день, тиждень або місяць.

Формат файлу з реєстром – XSL. Якщо за вказану дату операцій не було, прийде порожній реєстр.

Поля в реєстрі

Поле в реєстрі	Опис
Дата	Дата здійснення операції
ID операції	Унікальний ідентифікатор платежу, виплати або системної операції
ID магазину	Ідентифікатор вашого магазину в Feennex
Зараховано на магазин	Фактична сума, зарахована у ваш магазин з урахуванням комісій. Тільки для платежів.
Списано з магазину	Фактична сума, яка списана з вашого магазину при виплаті або службовій операції. Включає в себе комісію Feennex
Валюта	Валюта платежу — значення параметра `currency` із запиту на створення платежу при оплаті гаманцем або `shop_currency` із запиту на створення платежу при оплаті іншими способами. Можливі значення валют
Тип операції	Тип виконуваної операції. Можливі значення: Платежі, Виплати, Службова
Сума рахунку	Сума платежу — значення параметра `amount` із запиту на створення платежу при оплаті гаманцем або `shop_amount` із запиту на створення платежу при оплаті іншими способами
Валюта рахунку	Валюта платіжного напрямку. Можливі значення валют
Сума отримання	Сума платежу або виплати з урахуванням комісії. Тільки для виплат. Можливі значення валют
Валюта отримання	Валюта напрямку на виплату. Тільки для виплат. Можливі значення валют
Номер замовлення	Номер замовлення на вашій стороні
Опис	Опис операції — значення параметра `description` із запиту на створення платежу при оплаті гаманцем і іншими способами
Баланс	Поточний баланс вашого магазину після здійснення операції
Project ID	Службовий параметр. Не використовується
Комісія	Сума комісії платежу або виплати

Приклад реєстру

"Дата" "ID операции" "ID магазина" "Зачислено на магазин" "Списано с магазина" "Валюта" "Тип операции" "Сумма счета" "Валюта счета" "Сумма получения" "Валюта получения" "Номер заказа" "Описание" "Баланс" "Project ID" "Комиссия"
2024-04-19 17:07:43 50000000 1234 282,94 840 Платежи 301 840 i171e2d956-d3b4-457d-a26a-52d960 i171e2d956-d3b4-457d-a26a-52d960 9393,74 18,06

Про виплати

Виплата — це операція з перерахування грошей з балансу вашого магазину на гаманці Feennex або в сторонні платіжні системи.

Наприклад, ви отримали оплату від платника на рахунок вашого магазину і хочете вивести ці гроші на банківську картку.

Як проходять виплати

Якщо ви вже приймали платежі за допомогою Feennex, у вас вже є магазин або кілька магазинів. Кожен магазин має баланс – гроші, які вам перерахував платник.

Перед виплатою:

Перевірте стан рахунку вашого магазину в особистому кабінеті
Отримайте від вашого клієнта дані для проведення виплати, наприклад номер гаманця Feennex або банківської картки, на яку потрібно переказати гроші.
Перевірте, що ви вкладаєтеся в ліміти по виплатах, в залежності від способу отримання грошей, який вибрав клієнт. Актуальні ліміти вам повідомить менеджер.

Розмір комісії при виплатах ви можете уточнити у менеджера.

Способи отримання виплат

За допомогою API Feennex ви можете здійснювати виплати на гаманці Feennex і сторонні платіжні системи. Доступні платіжні системи для вашого магазину ви можете дізнатися в особистому кабінеті в налаштуваннях магазину в розділі Напрямки виведення. Для підключення додаткових платіжних систем зв'яжіться з менеджером.

Виплати на гаманці Feennex

Сценарій проведення виплати на гаманці Feennex

Крок 1. Не обов'язковий крок. Ви запитуєте попередній розрахунок виплати – надсилаєте Feennex POST-запит з даними про те, яку суму списати з балансу вашого магазину і на який гаманець її переказати.
Крок 2. Ви створюєте виплату – надсилаєте Feennex POST-запит з даними про те, яку суму списати з балансу вашого магазину і на який гаманець її переказати.

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

Проведення виплати через API

Крок 1. Запитайте попередній розрахунок виплати. У запиті передайте суму виплати, тип суми виплати, що передається, валюту отримання виплати, валюту списання з магазину, ідентифікатор вашого магазину. У параметрі sign передайте підпис запиту.

Приклад запиту

curl https://core.feennex.com/transfer/try \
   -H 'Content-Type: application/json' \
   -d '{
          "amount": 10,
          "amount_type": "receive_amount",
          "payee_currency": 840,
          "shop_currency": 840,
          "shop_id": 112,
          "sign": "cd30ba2b6e29f5"
       }'

Приклад відповіді

{
  "data": {
    "account_info_config": {
      "payee_account": {
        "comment": {
          "en": "Enter Wallet Number or Email",
          "ru": "Введите номер кошелька или email"
        },
        "example": "201557414711",
        "label": {
          "en": "Wallet Number or Email",
          "ru": "Введите номер кошелька или email"
        },
        "regex": "^20[\\d]{10}$|^([a-zA-Z0-9_-]+\\.)*[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*\\.[a-zA-Z]{2,6}$"
      }
    },
    "info": {},
    "payee_amount": 1.11,
    "payee_currency": 978,
    "shop_currency": 840,
    "write_off_amount": 1.19
  },
  "error_code": 0,
  "message": "Ok",
  "result": true
}

Крок 2. Створіть виплату на гаманець. У запиті передайте суму виплати, тип суми виплати, що передається, обліковий запис одержувача виплати в Feennex, валюту отримання виплати, валюту списання з магазину, ідентифікатор вашого магазину та унікальний ідентифікатор виплати на вашому боці. У параметрі sign передайте підпис запиту.

Приклад запиту

curl https://core.feennex.com/transfer/create \
   -H 'Content-Type: application/json' \
   -d '{
          "amount": 10,
          "amount_type": "receive_amount",
          "payee_account": "201497141132",
          "payee_currency": 840,
          "shop_currency": 840,
          "shop_id": 112,
          "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561324",
          "sign": "cd30ba2b6e29f5"
       }'

Приклад відповіді

{
  "data": {
    "balance": 88.91,
    "id": 12,
    "payee_account": 201497141132,
    "payee_amount": 10,
    "payee_currency": 840,
    "shop": 112,
    "shop_currency": 840,
    "write_off_amount": 10
  },
  "error_code": 0,
  "message": "Ok",
  "result": true
}

Виплата успішно пройшла!

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

Виплати на сторонні платіжні системи

Крок 1. Ви запитуєте попередній розрахунок виплати – надсилаєте Feennex POST-запит з даними про те, яку суму списати з балансу вашого магазину і на яку платіжну систему її переказати. У параметрі account_info_config можуть повернутися додаткові параметри, які потрібно передавати в наступних запитах
Крок 2. Ви перевіряєте можливість провести виплату в обрану платіжну систему з боку Feennex – надсилаєте Feennex POST-запит
Крок 3. Ви створюєте виплату — надсилаєте Feennex POST-запит з даними про те, яку суму списати з балансу вашого магазину і на яку платіжну систему її переказати. Feennex проводить виплату в обрану платіжну систему і повертає вам об'єкт виплати з актуальним статусом.
Крок 4. Ви, не частіше, ніж раз на хвилину, запитуєте статус виплати. Якщо статус — 5 (Success), виплата успішна, а гроші списані з балансу вашого магазину.

Проведення виплати через API

Крок 1. Запитайте попередній розрахунок виплати. У запиті передайте суму і валюту виплати, тип суми виплати, що передається, напрямок для виплати, ідентифікатор вашого магазину. У параметрі sign передайте підпис запиту.

Приклад запиту

curl https://core.feennex.com/withdraw/try \
   -H 'Content-Type: application/json' \
   -d '{
   
          "amount_type": "ps_amount",
          "shop_currency": 840,
          "sign": "f97c52fa8d273a",
          "payway": "card_usd",
          "amount": 1,
          "shop_id": 112
       }'

Приклад відповіді

{ 
"data": 
    { 
        "account_info_config"
        {
            "account": 
            {
                "regex": "\\d{9,15}$",
                "title": "79123456789"
            }
        }
     "payee_receive": 1,
    "ps_currency": 840,
    "shop_currency": 840,
    "shop_write_off": 1.02 
}, 
"error_code": 0, 
"message": "Ok", 
"result": true 
} 

Якщо у відповіді повертається об'єкт account_info_config з додатковими параметрами, ці параметри, крім account, вам потрібно передавати в запиті на Створення виплати в параметрі account_details.

Крок 2. Перевірте можливість провести виплату. У запиті передайте акаунт одержувача виплати для перевірки, напрямок для виплати, суму виплати, ідентифікатор магазину на вашому боці та додаткову інформацію про акаунт, якщо є. У параметрі sign передайте підпис запиту.

Приклад запиту

curl https://core.feennex.com/check_account \
   -H 'Content-Type: application/json' \
   -d '{
          "account": "4111111111111111",
          "account_details": {
            "contract": "C1234"
          },
          "sign": "faf7ee6db712752f2b107e05328bbd0d",
          "payway": "card_eur",
          "amount": 10.5,
          "shop_id": 1
       }'

Приклад відповіді

{
  "data": {
    "account_info": {
      "verified": "true"
    },
    "provider_status": 1,
    "result": true
  },
  "error_code": 0,
  "message": "Ok",
  "result": true
}

Крок 3. Створіть виплату на рахунок. У запиті передайте обліковий запис одержувача виплати, суму виплати, тип суми, що передається, напрямок виплати, валюту списання з магазину, ідентифікатор вашого магазину та унікальний ідентифікатор виплати на вашому боці. У параметрі sign передайте підпис запиту.

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

curl https://core.feennex.com/withdraw/create \
   -H 'Content-Type: application/json' \
   -d '{
          "account": "4111111111111111",
          "amount": 1,
          "amount_type": "ps_amount",
          "payway": "card_usd",
          "shop_currency": 840,
          "shop_id": 112,
          "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f",
          "sign": "b4c3ca4b403bb"
       }'

Приклад відповіді

{
  "data": {
    "balance": 0,
    "id": 11298076,
    "payee_receive": 1,
    "ps_currency": 840,
    "shop_currency": 840,
    "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f",
    "shop_write_off": 1.02,
    "status": 3
  },
  "error_code": 0,
  "message": "Ok",
  "result": true
}

Крок 4. Запитуйте статус виплати за ідентифікатором виплати або номером виплати у вашій системі. У запиті вкажіть час відправлення запиту, ідентифікатор вашого магазину та ідентифікатор виплати. У параметрі sign вкажіть підпис запиту.

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

curl https://core.feennex.com/withdraw/status \
   -H 'Content-Type: application/json' \
   -d '{
          "now": "2024-12-06 16:07:28.878200",
          "shop_id": 112,
          "withdraw_id": 11298076,
          "sign": "e1dfc97b2c5430"
       }'

Приклад об'єкта виплати в разі успіху

{
     "data": {
        "id": 11298076,
        "payee_receive": 1,
        "ps_currency": 840,
        "shop_currency": 840,
        "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f",
        "shop_write_off": 1.02,
        "status": 5
    }, 
    "result": True,
    "error_code": 0, 
    "message": "Ok"
}

Параметр status має значення 5, що відповідає успіху. Детальніше про статуси при виплатах на рахунок

Виплата успішно пройшла!

Group Прийом платежів: гаманець Feennex

Перед інтеграцією ознайомтеся з розділом Початок роботи з API

Створення платежу з оплатою гаманцем bill/create [/bill/create]

За допомогою цього методу ви можете створити платіж для прийому оплати з гаманців Feennex.

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

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: payer_currency, shop_amount, shop_currency, shop_id і shop_order_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/bill/create \
   -H 'Content-Type: application/json' \
   -d '{
          "description": "Оплата заказа", 
          "payer_currency": 840, 
          "shop_amount": "23.15", 
          "shop_currency": 840, 
          "shop_id": "3", 
          "shop_order_id": 4239, 
          "sign": "ad7fbe8df102b" 
       }'

Приклад відповіді при помилці

{
    "data": null,
    "message": "invalid sign",
    "error_code": 1,
    "result": false
}

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

POST Створити платіж для оплати гаманцем [POST]

Request (application/json)
- Attributes
  - payer_currency: 840 (number, required) - Валюта, в якій проводить оплату платник. Ця валюта може відрізнятися від валюти магазину. Можливі значення валют
  - shop_amount: 23.15 (string, required) - Сума платежу
  - shop_currency: 840 (number, required) - Валюта, в якій оплата зараховується у ваш магазин. Можливі значення валют
  - shop_id: 3 (number, required) - Ідентифікатор вашого магазину в Feennex
  - shop_order_id: 123456789 (string, required) - Унікальний номер замовлення у вашій системі. Не більше 255 символів
  - sign: 32b2c32caa8ad (string, required) - Підпис запиту
  - description: Оплата замовлення (string, optional) - Опис платежу. Не більше 255 символів
  - payer_account: 1a2b3c (string, optional) - Обліковий запис Feennex платника, який проводить оплату
  - lifetime: 43200 (number, optional) Час життя платежу в хвилинах. Коли платіж буде прострочено, його статус зміниться на Expired. Якщо параметр не передавати, час життя складе 43200 хвилин
  - failed_url: https://feennex.com/failed (string, optional) - URL-адреса, на яку перенаправляється платник після неуспішної оплати. Якщо хочете передавати URL-адресу в запиті, видаліть значення відповідної адреси з налаштувань магазину
  - success_url: https://feennex.com/success (string, optional) - URL-адреса, на яку перенаправляється платник після успішної оплати. Якщо хочете передавати URL-адресу в запиті, видаліть значення відповідної адреси з налаштувань магазину
  - callback_url (string, optional) - URL-адреса, на яку відправляється повідомлення про успішну оплату. Якщо хочете передавати URL-адресу в запиті, видаліть значення відповідної адреси з налаштувань магазину
  - callback_rejected_url (string, optional) - URL-адреса, на яку відправляється повідомлення про неуспішну оплату. Якщо хочете передавати URL-адресу в запиті, видаліть значення відповідної адреси з налаштувань магазину
- Body
```
{ 
    "description": "Оплата замовлення", 
    "payer_currency": 840, 
    "shop_amount": "23.15", 
    "shop_currency": 840, 
    "shop_id": "3", 
    "shop_order_id": 4239, 
    "sign": "ad7fbe8df102b" 
}
```
Response 200 (application/json)
- Headers
- Body
```
{
    "data": {
        "created": "Wed, 10 Apr 2024 14:18:19 GMT",
        "id": 26,
        "lifetime": 43200,
        "payer_account": null,
        "payer_currency": 840,
        "payer_price": 500,
        "shop_amount": 500,
        "shop_currency": 840,
        "shop_id": 3,
        "shop_order_id": "4239",
        "shop_refund": 465,
        "url": "https://wallet.feennex.com/en/bill/pay/Waptm"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}
```
- Attributes (object)
  - data (object, required) - Об’єкт містить дані для оплати
    - created: Wed, 10 Apr 2024 14:18:19 GMT (string, required) - Дата створення платежу. Формат: RFC 5322
    - id: 26 (number, required) - Унікальний ідентифікатор платежу в Feennex
    - lifetime: 43200 (number, required) - Час життя платежу в хвилинах. Коли платіж буде прострочено, його статус зміниться на Expired. Значення за замовчуванням – 43200 хвилин
    - payer_account: 1a2b3c (string, optional) - Обліковий запис Feennex платника, який проводить оплату. Повертається, якщо ви передавали цей параметр у запиті
    - payer_currency: 840 (number, required) - Валюта, в якій проводить оплату платник. Ця валюта може відрізнятися від валюти магазину. Можливі значення валют
    - payer_price: 23.15 (number, required) - Сума, яку повинен оплатити платник. Включає в себе комісію Feennex
    - shop_amount: 10.0 (number, required) - Сума платежу
    - shop_currency: 840 (number, required) - Валюта, в якій оплата зараховується у ваш магазин. Можливі значення валют
    - shop_id: 3 (number, required) - Ідентифікатор вашого магазину в Feennex
    - shop_order_id: 101 (string, required) - Унікальний ідентифікатор замовлення у вашій системі. Не більше 255 символів
    - url: https://wallet.feennex.com/en/bill/pay/Waptm (string, required) - URL-адреса, на яку вам потрібно переадресувати платника
  - error_code: 0 (number, required) - Код помилки. Можливі значення кодів помилок
  - message: Ok (string, required) - Опис помилки. За значенням цього параметра можна визначити успішність запиту і зрозуміти, що пішло не так
  - result: true (boolean, required) - Успішність запиту

Запит статусу платежу при оплаті гаманцем bill/shop_order_status [/bill/shop_order_status]

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

Важливо! Запит статусу необхідно робити не частіше ніж раз на 10 секунд.

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: now, shop_id і shop_order_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/bill/shop_order_status \
   -H 'Content-Type: application/json' \
   -d '{
          "now": "2024-05-01 16:56:25.009469", 
          "shop_id": "1092", 
          "shop_order_id": "234234232323",
          "sign": "ad7fbe8df102b" 
       }'

Приклад відповіді при помилці

{
    "data": null,
    "message": "invalid sign",
    "error_code": 1,
    "result": false
}

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

POST Запитати статус платежу при оплаті гаманцем [POST]

Request (application/json)
- Attributes
  - now (string, required) - Дата і час, коли ви надсилаєте запит. Формат: ISO 8601
  - shop_id: 1092 (number, required) - Ідентифікатор вашого магазину в Feennex
  - shop_order_id: 123456789 (string, required) - Унікальний номер замовлення у вашій системі. Не більше 255 символів
  - sign: 32b2c32caa8ad (string, required) - Підпис запиту
- Body
```
{ 
    "now": "2024-05-01 16:56:25.009469", 
    "shop_id": "1092", 
    "shop_order_id": "234234232323",
    "sign": "ad7fbe8df102b" 
} 
```
Response 200 (application/json)
- Headers
- Body
```
{
    "data": 
    {
      "client_price": 1.16, 
      "created": "2024-10-20 14:01:28", 
      "description": "Main account", 
      "is_unique": true, 
      "payment_id": 852095, 
      "payway": "feennex_usd", 
      "processed": "2024-10-20 14:01:33", 
      "ps_currency": 840, 
      "ps_data": {
        "ps_payer_account": "201538122124"
      }, 
      "shop_amount": 1.1, 
      "shop_currency": 840, 
      "shop_id": 1092, 
      "shop_order_id": "234234232323", 
      "shop_refund": 1.1, 
      "status": 2
    }, 
    "error_code": 0, 
    "message": "Ok", 
    "result": true
}
```
- Attributes (object)
  - data (object, required) - Об’єкт містить дані про платіж
    - client_price: 1.16 (number, required) - Сума, яку фактично переказав платник
    - created: 2024-10-20 14:01:28 (string, required) - Дата і час створення платежу. Формат: ISO 8601
    - is_unique (boolean, required) - Унікальність номера замовлення на стороні вашого магазину. Якщо ви вже створювали платіж із таким номером замовлення, повертається false. У цьому випадку метод повертає інформацію про останній створений платіж з оплатою гаманцем
    - payment_id: 852095 (number, required) - Ідентифікатор платежу на стороні Feennex
    - payway: feennex_usd (string, required) - Платіжний напрям
    - processed (string, required) - Дата проведення платежу. Формат: ISO 8601
    - ps_currency: 840 (number, required) - Валюта отримання платежу в платіжній системі
    - ps_data (object, required) - Додаткова інформація від платіжної системи, наприклад акаунт платника ps_payer_account: 201538122124 (string, required) - Акаунт платника в Feennex
    - shop_amount: 10.0 (number, required) - Сума платежу
    - shop_currency: 840 (number, required) - Валюта, в якій платіж зараховується у магазин
    - shop_id: 3 (number, required) - Ідентифікатор вашого магазину в Feennex
    - shop_order_id: 101 (string, required) - Унікальний номер замовлення у вашій системі. Не більше 255 символів
    - shop_refund: 1.1 (number, required) - Сума зарахування на баланс магазину, у валюті рахунку
    - status: 2 (number, required) - Статус платежу. Докладніше про статуси
    - description: Main account (string, optional) - Опис платежу. Не більше 255 символів
  - error_code: 0 (number, required) - Код помилки. Можливі значення кодів помилок
  - message: Ok (string, required) - Опис помилки. За значенням цього параметра можна визначити успішність запиту і дізнатися, що пішло не так
  - result: true (boolean, required) - Успішність запиту

Group Прийом платежів: сторонні платіжні системи

Перед інтеграцією ознайомтеся з розділом Початок роботи з API

Попередній розрахунок платежу invoice/try [/invoice/try]

Метод не обов'язковий. Повертає додаткову інформацію для створення платежу з попереднім розрахунком комісії.

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: shop_id, amount, currency, payway и shop_order_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/invoice/try \
   -H 'Content-Type: application/json' \
   -d '{
          "currency": 840,
          "sign": "912b985f1895962",
          "payway": "card_usd",
          "amount": 12.34,
          "shop_id": 112,
          "shop_order_id": 4128
       }'

Приклад відповіді при помилці

{
    "data": null,
    "error_code": 4,
    "message": "Payer price amount is too small, min: 1.0",
    "result": false
}

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

Розрахувати платіж [POST]

Headers
Content-Type: application/json
Request (application/json)
- Attributes
  - shop_id: 5 (number, required) - Ідентифікатор вашого магазину в Feennex
  - amount: 100 (number, required) - Сума платежу
  - currency: 840 (number, required) - Валюта платежу. Можливі значення валют
  - payway: card_usd (string, required) - Платіжний напрямок, для якого проходить розрахунок. Можливі значення ви можете уточнити в особистому кабінеті в налаштуваннях магазину в розділі Методи оплати.
  - sign: a7f5bcbb774ce (string, required) – Підпис запиту
  - shop_order_id (string, required) - Унікальний номер замовлення у вашій системі. Не більше 255 символів
  - description: Оплата заказа (string, optional) – Опис платежу. Не більше 255 символів
- Body
```
{
    "currency": 840,
    "sign": "912b985f1895962",
    "payway": "card_usd",
    "amount": 12.34,
    "shop_id": 112,
    "shop_order_id": 4128
}
```
Response 200 (application/json)
- Headers
- Body
```
{
    "data": {
        "add_ons_config": {
            "email": {
                "example": "[email protected]",
                "label": {
                    "en": "E-mail:",
                    "ru": "E-mail:",
                    "uk": "E-mail:"
                },
                "regex": "^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$",
                "title": {
                    "en": "Enter your e-mail",
                    "ru": "Введите Ваш e-mail",
                    "uk": "Введіть Ваш e-mail"
                }
            }
        },
        "exch_fee": 0,
        "info": null,
        "manual": 1,
        "payer_fee": 0,
        "payer_price": 500,
        "paymethod_id": 268,
        "paymethod_name": "Банк h2h",
        "ps_currency": 840,
        "warning": null
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}
```
- Attributes (object)
  - data (object, required) - Об'єкт містить дані про попередній розрахунок платежу
    - add_ons_config (object, required) - додаткова інформація, якщо вона потрібна за платіжним напрямком
    - exch_fee: 0 (number, required) - Комісія при конвертації
    - info: null (string, required) - Додаткова інформація про платіж
    - manual: 1 (number, required) - Службовий параметр
    - payer_fee: 0 (number, required) - Розмір комісії
    - payer_price: 500 (number, required) - Сума, яку повинен сплатити платник. Включає в себе комісію Feennex
    - paymethod_id: 268 (number, required) - Ідентифікатор платіжного напрямку
    - paymethod_name: Банк h2h (string, required) - Назва платіжного напрямку
    - ps_currency: 840 (number, required) - Валюта отримання платежу в платіжній системі
    - warning: null (string, required) - Службовий параметр
  - error_code: 0 (number, required) - Код помилки. Можливі значення кодів помилок
  - message: Ok (string, required) - Містить опис помилки. Приклад: «Ok». За значенням цього параметра можна визначити успішність запиту і дізнатися, що пішло не так.
  - result: true (boolean, required) - Успішність запиту

Створення платежу invoice/create [/invoice/create]

За допомогою цього методу ви можете створити платіж для прийому оплати будь-якими способами, крім гаманців Feennex.

Важливо! Якщо ви хочете прийняти оплату за допомогою гаманця Feennex, створіть платіж за допомогою методу Створення платежу з оплатою гаманцем

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: shop_id, amount, email, currency, payway и shop_order_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/invoice/create \
   -H 'Content-Type: application/json' \
   -d '{
          "currency": 840,
          "sign": "a7f5bcbb774ce",
          "payway": "card_usd",
          "amount": 12.34,
          "shop_id": 112,
          "shop_order_id": 4129,
          "description": "Оплата заказа"
       }'

Приклад відповіді при помилці

{
    "data": null,
    "error_code": 4,
    "message": "Payer price amount is too small, min: 1.0",
    "result": false
}

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

POST Створити платіж [POST]

Request (application/json)
- Attributes
  - shop_id: 5 (number, required) - Ідентифікатор вашого магазину в Feennex
  - amount: 100 (number, required) - Сума платежу
  - email: [email protected] (string, required) - Електронна пошта платника. Не бере участі у формуванні підпису
  - currency: 840 (number, required) - Валюта виставленого рахунку. Можливі значення валют
  - payway: card_usd (string, required) - Платіжний напрямок. Можливі значення ви можете уточнити в особистому кабінеті в настройках магазина в разделе Методы оплаты
  - sign (string, required) – Підпис запиту
  - shop_order_id (string, required) - Унікальний номер замовлення у вашій системі. Не більше 255 символів
  - description: Оплата заказа (string, optional) – Опис платежу. Не більше 255 символів
  - failed_url: https://feennex.com/failed (string, optional) - URL-адреса, на яку перенаправляється платник після невдалої оплати. Якщо хочете передавати URL-адресу в запиті, видаліть значення відповідної адреси з налаштувань магазину
  - success_url: https://feennex.com/success (string, optional) - URL-адреса, на яку перенаправляється платник після невдалої оплати. Якщо хочете передавати URL-адресу в запиті, видаліть значення відповідної адреси з налаштувань магазину
  - callback_url (string, optional) - URL-адреса, на яку надсилається повідомлення про успішну оплату. Якщо ви хочете передавати URL-адресу в запиті, видаліть значення відповідної адреси з [налаштувань магазину].(https://wallet.feennex.com/shops)
  - callback_rejected_url (string, optional) - URL-адреса, на яку надсилається повідомлення про невдалу оплату. Якщо ви хочете передати URL-адресу в запиті, видаліть значення відповідної адреси з [налаштувань магазину].(https://wallet.feennex.com/shops)
- Body
```
{
    "currency": "840",
    "payway": "card_usd",
    "amount": "12.34",
    "email": "[email protected]",
    "shop_id": 112,
    "shop_order_id": 4129,
    "description": "Оплата заказа" ,
    "sign":"a7f5bcbb774ce"
}
```
Response 200 (application/json)
- Headers
- Body
```
{
    "data": {
        "data": {
            "session_id": "3067894a580242dd86e03890506a88b"
        },
        "id": 499564464,
        "method": "GET",
        "url": "https://example.com"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}
```
- Attributes (object)
  - data (object, required) - Об'єкт містить інформацію про платіж
    - data (object, required) - Дані платежу
      - session_id (string, optional) - Ідентифікатор сесії. Параметр повертається, якщо в параметрі payway ви передали card-rub
      - language: en (string, optional) - Службовий параметр
      - mdOrder (string, optional) - Службовий параметр
    - method: GET (string, required) - Тип запиту, яким вам потрібно перенаправити платника на URL-адресу з параметра url
    - url: https://epg.guavapay.com/epg/merchants/Skillgurus_PSX/payment.html (string, required) - URL-адреса, на яку потрібно перенаправити платника
    - id: 489222674 (number, required) - унікальний ідентифікатор платежу в Feennex
  - error_code: 0 (number, required) - Код помилки. Можливі значення кодів помилок
  - message: Ok (string, required) - Опис помилки. За значенням цього параметра можна визначити успішність запиту і дізнатися, що пішло не так.
  - result: true (boolean, required) - Успішність запиту

Запит статусу платежу invoice/check [/invoice/check]

Метод дозволяє дізнатися статус створеного платежу, якщо для оплати платник використовував будь-які доступні способи оплати, крім гаманця Feennex.

Важливо! Щоб дізнатися статус платежу, який ви створили для оплати гаманцем, використовуйте метод Запит статусу платежу з оплатою гаманцем

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

curl https://core.feennex.com/invoice/check \
   -H “Content-Type: application/json” \
   -d '{
          «now»: «2024-04-10 12:59:13», 
          «shop_id»: «1», 
          «shop_order_id»: «123456789»,
          «sign»: «32b2c32caa8ad» 
       }'

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

POST Запит статусу платежу [POST]

Request (application/json)
- Attributes
  - now (string, required) - Дата и время, когда вы отправляете запрос. Формат: ISO 8601
  - shop_id: 1 (number, required) - Идентификатор вашего магазина в Feennex
  - shop_order_id: "123456789" (string, required) - Уникальный номер заказа в вашей системе. Не более 255 символов
  - sign: 32b2c32caa8ad (string, required) - Подпись запроса
- Body
```
{
    "now": "2024-04-10 12:59:13",
    "shop_id": 1,
    "shop_order_id": "123456789",
    "sign": "32b2c32caa8ad"
}
```
Response 200 (application/json)
- Headers
- Body
```
{
   "data":{
      "client_price":10.2,
      "created":"2024-04-10 12:59:13",
      "description":"Оплата заказа",
      "is_unique":false,
      "payment_id":11639480,
      "payway":"card_usd",
      "processed":null,
      "ps_currency":840,
      "ps_data":null,
      "shop_amount":10.0,
      "shop_currency":840,
      "shop_id":3,
      "shop_order_id":"101",
      "shop_refund":9.6,
      "status":2,
      "updated":null
   },
   "error_code":0,
   "message":"Ok",
   "result":true
}    
```
- Attributes (object)
  - data (object, required) - Объект содержит информацию о платеже
    - client_price: 1000.2 (number, required) - Фактическая сумма, которую оплатил плательщик
    - created: 2024-04-10 12:59:13 (string, required) - Дата и время создания платежа. Формат: ISO 8601
    - description: Оплата заказа (string, optional) - Описание платежа. Не более 255 символов
    - is_unique: false (boolean, required) - Уникальность номера заказа
    - payment_id: 11639480 (number, required) - Идентификатор платежа
    - payway: card_usd (string, required) - Платежное направление. Возможные значения вы можете уточнить в личном кабинете в настройках магазина в разделе Методы оплаты
    - processed (string, required) - Дата проведения платежа. Формат: ISO 8601
    - ps_currency: 840 (number, required) - Валюта получения платежа в платежной системе
    - ps_data (object, required) - Дополнительная информация от платежной системы, например аккаунт плательщика
      - amount (number, optional) - Сумма, которую должен перевести плательщик
      - qr_data (string, optional) - URL-адрес, который ведет на сайт банка на форму отправки перевода. Вам нужно самостоятельно сгенерировать QR-код из этого адреса и отобразить плательщику на платежной странице. Только для способа оплаты Перевод на банковский счет с помощью QR-кода.
      - qr_caption (string, optional) - Номер договора получателя перевода. Только для способа оплаты Перевод на банковский счет с помощью QR-кода.
      - bank: ТИНЬКОФФ (string, optional) - Название банка, в который плательщик делает перевод. Только для способа оплаты Перевод на банковский счет с помощью СБП
      - card (string, optional) - Номер банковской карты, на которую плательщик делает перевод. Только для способа оплаты Перевод на банковский счет с помощью перевод на счет
      - card_holder_name: Иванов Иван Иванович (string, optional) - ФИО физического лица, которому плательщик делает перевод. Только для способа оплаты Перевод на банковский счет с помощью номера карты
      - expired: 1707152043.557505 (string, optional) - Время, до которого плательщик должен отправить перевод. Рекомендуется предупреждать об этом плательщика. Только для способа оплаты Перевод на банковский счет
      - phone:79999999999 (string, optional) - Телефон физического лица, которому плательщик делает перевод. Только для способа оплаты Перевод на банковский счет с помощью СБП
      - currency (string, optional) - Валюта при переводе на счет. Возможные значения валют
      - method (string, optional) - код способа оплаты. Возможные значения вам сообщит менеджер
      - url (string, optional) - URL-адрес, из которого нужно сгенерировать QR-код. Значение возвращается, если параметр method имеет значение qr. В остальных случаях возвращается пустое значение
      - receipt_url (string, optional) - URL-адрес для загрузки чека по API. Возвращается, если способ оплаты – Перевод на банковский счет
      - receipt_status_url (string, optional) - URL-адрес для проверки статуса чека по API. Возвращается, если способ оплаты – Перевод на банковский счет
      - receipt_web (string, optional) - URL-адрес для загрузки чека через форму. На этот адрес вам нужно перенаправить плательщика, если вы не хотите реализовывать форму загрузки чека. Возвращается, если способ оплаты – Перевод на банковский счет
    - shop_amount: 10.0 (number, required) - Сумма, которую фактически оплатил плательщик
    - shop_currency: 840 (number, required) - Валюта, в которой платеж зачисляется в магазин
    - shop_id: 3 (number, required) - Идентификатор вашего магазина в Feennex
    - shop_order_id: 101 (string, required) - Уникальный номер заказа в вашей системе. Не более 255 символов
    - shop_original_amount (number, optional) - Изначальная сумма платежа. Возвращается, если плательщик перевел не ту сумму
    - shop_refund: 9.6 (number, required) - Сумма, которая поступит на счет вашего магазина
    - status: 2 (number, required) - Статус счета. Подробнее про статусы платежей
    - updated (number, required) - Дата и время последнего изменения статуса платежа. Формат: ISO 8601. Запрос статуса необходимо делать не чаще чем раз в 10 секунд. Если shop_order_id не уникален, в ответе содержится "is_unique":false, а метод возвращает информацию по последнему созданному платежу
  - error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
  - message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
  - result: true (boolean, required) - Успешность запроса

Дані для HTML-форми [/h2h_data]

Тільки для сценарію Самостійна інтеграція Host-to-Host при оплаті банківською карткою.

Запит повертає токен і URL-адресу, які потрібні для формування HTML-форми з картковими даними платника.

Формувати підпис для цього запиту не потрібно.

Production URL вам надасть менеджер.

Обов’язковий параметр запиту: session_id

curl https://example.com/h2h_data \
   -H 'Content-Type: application/json' \
   -d '{
          "session_id": "26d90ef012e34b44aa9d74a3556e15a6"
       }'

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

POST Запит даних для HTML-форми [POST]

Request (application/json)
- Attributes
  - session_id: 26d90ef012e34b44aa9d74a3556e15a6 (required, string) - Идентификатор сессии, который вы получили в ответе на запрос Создание платежа
- Body
```
{
    "session_id": "26d90ef012e34b44aa9d74a3556e15a6"
}
```
Response 200 ()
- Body
```
{
  "data":
  {
    "form_token": "uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8", 
    "payform_url": "https://example.com/payform",
  },
  "error_code": 0, 
  "message": "Ok", 
  "result": true 
}
```
- Attributes (object)
  - form_token: uerhdw47d748yd784dy83uhueh834h84dh84hd8dh8 (string, required) - Токен для передачи карточных данных
  - payform_url: https://example.com/payform (string, required) - URL-адрес для редиректа пользователя с карточными данными

Надсилання чеків order/`{id}`/receipt [/api/v1/order/`{id}`/receipt]

Тільки для сценарію Самостійна інтеграція Host-to-Host і тих, хто самостійно реалізовує сторінку завантаження чеку.

Метод дозволяє надіслати в службу підтримки Feennex чек, який вам передав платник. Формувати підпис для цього запиту не потрібно.

Адресу для надсилання запиту та значення параметра id вам потрібно отримати при запиті статусу платежу.

Докладніше про надсилання чеків

Обов’язковий параметр запиту: file

Приклад запиту

curl -X POST \ 
--location 'https://<baseURL>/api/v1/order/{id}/receipt' \
--form 'file=@"/home/cwm/Pictures/receipt.jpg"'

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

POST Надіслати чек [POST]

Request (application/json)
- Attributes
  - file: /home/cwm/Pictures/receipt.jpg (required, string) - Путь к изображению с чеком. Поддерживаемые форматы: JPEG, JPG, PNG, PDF, WebP, HEIF. Размер изображения не должен превышать 10 МБ
Response 200 (application/json)
- Body
  
  null

Response 400 (application/json)

Body

{
    "detail": "File type: application/zip not allowed"
}

Отримання статусу чека order/`{id}`/receipt/status [/api/v1/order/`{id}`/receipt/status]

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

Детальніше про відправлення чеків

Приклад запиту

curl -X GET \ 
--location 'https://<baseURL>/api/v1/order/{id}/receipt/status' \

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

GET Отримати статус чека [GET]

Response 200
- Body
  
  [
```
{
    "id": "c9e35f42-62de-45c4-8092-152ba47d81e5",
    "status": "pending",
    "comment": null
}
```
  ]
- Attributes (object)
  - id (string, required) - Уникальный идентификатор чека
  - status: pending (string, required) - Статус чека. Возможные значения: pending, succeeded, rejected. Подробнее про статусы чека
  - comment: null (string, optional) - Комментарий к чеку от технической поддержки Feennex

Response 422

Body

{
    "detail": [
        {
            "loc": [
                "query",
                "order_id"
            ],
            "msg": "value is not a valid uuid",
            "type": "type_error.uuid"
        }
    ]
}      

Group Виплата на гаманець Feennex

Перед інтеграцією ознайомтеся з розділом Початок роботи з API

Попередній розрахунок виплати на гаманець Feennex transfer/try [/transfer/try]

Метод не обов'язковий для створення виплати на гаманець. Повертає додаткову інформацію для створення виплати на гаманець з попереднім розрахунком комісії.

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: amount, amount_type, payee_currency, shop_currency і shop_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/transfer/try \
   -H 'Content-Type: application/json' \
   -d '{
          "amount": 1.11,
          "amount_type": "receive_amount",
          "payee_currency": 978,
          "shop_currency": 840,
          "shop_id": 6,
          "sign": "cea33ec0eeeef98"
       }'

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

POST Попередній розрахунок виплати [POST]

Request (application/json)
- Attributes
  - amount: 1 (number, required) - Сумма получения или списания, зависит от значения amount_type
  - amount_type: receive_amount (string, required) - Определяет тип суммы. receive_amount – сумма выплаты, которая поступит на кошелек, writeoff_amount - сумма, которая спишется с баланса вашего магазина
  - payee_currency: 840 (string, required) - Валюта, в которой выплата поступит на кошелек Feennex. Возможные значения валют
  - shop_currency: 840 (number, required) - Валюта, с которой выплата спишется со счета вашего магазина. Возможные значения валют
  - shop_id: 1 (number, required) - Идентификатор вашего магазина, с которого проходит выплата
  - sign: cea33ec0eeeef98 (string, required) - Подпись запроса
- Body
```
{
   "amount": 1.11,
   "amount_type": "receive_amount",
   "payee_currency": 978,
   "shop_currency": 840,
   "shop_id": 6,
   "sign": "cea33ec0eeeef98"
}
```
Response 200 (application/json)
- Headers
- Body
```
{
    "data": {
        "account_info_config": {
            "payee_account": {
                "comment": {
                    "en": "Enter Wallet Number or Email",
                    "ru": "Введите номер кошелька или email"
                },
                "example": "201557414711",
                "label": {
                    "en": "Wallet Number or Email",
                    "ru": "Введите номер кошелька или email"
                },
                "regex": "^20[\\d]{10}$|^([a-zA-Z0-9_-]+\\.)*[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*\\.[a-zA-Z]{2,6}$"
            }
        },
        "info": {},
        "payee_amount": 1.11,
        "payee_currency": 978,
        "shop_currency": 840,
        "write_off_amount": 1.19
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}   
```
- Attributes (object)
  - data (object, required) - Объект содержит информацию о выплате
    - account_info_config (object, required) - Информация об аккаунте, на который будет выплата
      - payee_account (object, required) - Дополнительная информация об аккаунте, на который будет выплата. Параметры в объекте могут отличаться для каждого направления на выплату
    - info (object, required) - Служебный параметр
    - payee_amount: 1.11 (number, required) - Сумма, которая поступит на ваш счет
    - payee_currency: 978 (number, required) - Валюта суммы, которая поступит на ваш счет
    - shop_currency: 840 (number, required) - Валюта суммы, которая спишется со счета вашего магазина
    - write_off_amount (number, required) - Сумма, которая спишется со счета магазина
  - error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
  - message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
  - result: true (boolean, required) - Успешность запроса

Виплата на гаманець Feennex transfer/create [/transfer/create]

За допомогою цього методу ви можете створити виплату для переказу грошей з балансу магазину на ваш гаманець Feennex.

Важливо! Після створення виплати на гаманець у відповіді не повертається статус. Якщо виплата на гаманець створена, а у відповіді повернувся ідентифікатор виплати (параметр id), то виплата вважається успішною. Більше нічого робити не потрібно.

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: amount, amount_type, payee_account, payee_currency, shop_currency, shop_id і shop_payment_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/transfer/create \
   -H 'Content-Type: application/json' \
   -d '{
          "amount": 10,
          "amount_type": "receive_amount",
          "payee_account": "201497141132",
          "payee_currency": 840,
          "shop_currency": 840,
          "shop_id": 112,
          "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561324",
          "sign": "cd30ba2b6e29f5"
       }'

Детальніше про виплати на гаманець Feennex

Метод не є обов'язковим для створення виплати на гаманець. Повертає додаткову інформацію для створення виплати на гаманець з попереднім розрахунком комісії.

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

Створення виплати на гаманець [POST]

Request (application/json)
- Headers
- Attributes
  - amount: 1 (number, required) - Сумма получения или списания. Зависит от параметра amount_type
  - amount_type: receive_amount (string, required) - Определяет тип суммы. Возможные значения: receive_amount – сумма, которая поступит на ваш аккаунт с учетом всех комиссий. writeoff_amount - сумма, которая спишется с баланса магазина. Не включает в себя комиссию
  - payee_account: 201497141132 (string, required) - Аккаунт получателя денег в Feennex. Можно передать номер кошелька или email
  - payee_currency: 840 (string, required) - Валюта, в которой выплата поступит на аккаунт в Feennex. Возможные значения валют
  - shop_currency: 840 (number, required) - Валюта, в которой выплата спишется с вашего магазина. Возможные значения валют
  - shop_id: 1 (number, required) - Идентификатор вашего магазина, с которого осуществляется выплата
  - shop_payment_id (string, required) - Идентификатор выплаты на вашей стороне. Должен быть уникальным для каждой новой выплаты.
  - sign: cd30ba2b6e29f5 (string, required) - Подпись запроса
- Body
```
{
    "amount": 10,
    "amount_type": "receive_amount",
    "payee_account": "201497141132",
    "payee_currency": 840,
    "shop_currency": 840,
    "shop_id": 112,
    "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561324",
    "sign": "cd30ba2b6e29f5"
}
```
Response 200 ()
- Body
```
{
    "data": {
        "balance": 88.91,
        "id": 12,
        "payee_account": 201497141132,
        "payee_amount": 10,
        "payee_currency": 840,
        "shop": 112,
        "shop_currency": 840,
        "write_off_amount": 10
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}
```
- Attributes (object)
  - data (object, required) - Объект содержит данные о выплате
    - balance: 88.91 (number, required) - Баланс вашего магазина после выплаты
    - id (number, required) - Уникальный идентификатор выплаты
    - payee_account: 201497141132 (number, required) - Аккаунт получателя денег в системе Feennex. Можно передать номер кошелька или email
    - payee_currency: 840 (number, required) - Валюта, в которой выплата поступит на кошелек
    - shop: 112 (number, required) - Идентификатор магазина Feennex
    - shop_currency (number, required) - Валюта, в которой выплата спишется со счета вашего магазина
    - write_off_amount (number, required) - Сумма, которая спишется со счета магазина
  - error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
  - message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
  - result: true (boolean, required) - Успешность запроса

Запит статусу виплати на гаманець transfer/shop_payment_status [/transfer/shop_payment_status]

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

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

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/shop_payment_status \
   -H 'Content-Type: application/json' \
   -d '{
          "shop_id": 112, 
          "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561322", 
          "now": "2024-12-06 16:07:28.878200", 
          "sign": "e76c5ed9431d"
       }'

Приклад відповіді, якщо виплата створена і успішно проведена

{
  "data": {
    "id": 3,
    "payee_currency": 840,
    "receive_amount": 1,
    "shop_currency": 840,
    "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561322",
    "write_off_amount": 1
  },
  "error_code": 0,
  "message": "Ok",
  "result": true
}

Приклад відповіді при помилці

{ 
    "data": null, 
    "error_code": 7, 
    "message": "Transfer (shop_payment_id=test) wasn't found", 
    "result": false 
} 

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

Запитати статус виплати на гаманець [POST]

Headers
Content-Type: application/json
Request (application/json)
- Attributes
  - now (string, required) - Дата и время, когда вы отправляете запрос. Формат: ISO 8601
  - shop_id: 1 (number, required) - Идентификатор вашего магазина, с которого осуществляется выплата
  - shop_payment_id (string, required) - Идентификатор выплаты на вашей стороне. Должен быть уникальным для каждой новой выплаты.
  - sign: cd30ba2b6e29f5 (string, required) - Подпись запроса
- Body
```
{ 
    "shop_id": 112, 
    "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561322", 
    "now": "2024-12-06 16:07:28.878200", 
    "sign": "e76c5ed9431d" 
} 
```
Response 200 ()
- Body
```
{ 
    "data": 
        { 
            "id": 3, 
            "payee_currency": 840, 
            "receive_amount": 1, 
            "shop_currency": 840, 
            "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561322", 
            "write_off_amount": 1 
        }, 
        "error_code": 0, 
        "message": "Ok", 
        "result": true 
}  
```
- Attributes (object)
  - data (object, required) - Объект содержит данные о выплате
    - id (number, required) - Идентификатор выплаты
    - payee_currency: 840 (number, required) - Валюта выплаты, которая поступит на ваш кошелек
    - receive_amount: 1 (number, required) – Сумма, которая поступит на ваш кошелек
    - shop_currency: 840 (number, required) - Валюта, в которой выплата спишется со счета вашего магазина
    - shop_payment_id (string, required) - Уникальный идентификатор платежа на стороне вашего магазина;
    - write_off_amount (number, required) - Сумма списания с магазина. ВАлюта этой суммы соответствует значению параметра shop_currency
  - error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
  - message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
  - result: true (boolean, required) - Успешность запроса

Group Виплата на рахунок у сторонній платіжній системі

Перед інтеграцією ознайомтеся з розділом Початок роботи з API

Попередній розрахунок виплати withdraw/try [/withdraw/try]

Метод не обов'язковий. Повертає додаткову інформацію для створення виплати з попереднім розрахунком комісії.

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: shop_currency, amount_type, payway, amount, shop_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/withdraw/try \
   -H 'Content-Type: application/json' \
   -d '{
   
          "amount_type": "ps_amount", 
          "shop_currency": 840,
          "sign": "32b2c32caa8ad",
          "payway": "card_usd",
          "amount": 1,
          "shop_id": 112 
       }'

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

Запитати розрахунок виплати [POST]

Request (application/json)
- Headers
- Attributes
  - shop_currency: 840 (number, required) - Валюта списания выплаты со счета вашего магазина. Возможные значения валют
  - amount_type: receive_amount (string, required) - Определяет тип суммы. Возможные значения: ps_amount – сумма, которая поступит на счет получателя в платежной системе, shop_amount – сумма, которая спишется с баланса вашего магазина
  - sign: 32b2c32caa8ad (string, required) - Подпись запроса
  - payway: card_usd (string, required) - Направление для выплаты. Возможные значения вы можете узнать в личном кабинете в настройках магазина в разделе Направления вывода. Валюта получения зависит от переданного направления для выплаты
  - amount: 1 (number, required) - Сумма получения или списания. Зависит от значения параметра amount_type
  - shop_id: 1 (number, required) - Идентификатор вашего магазина, с которого осуществляется выплата
- Body
```
{ 
    "amount_type": "ps_amount", 
    "shop_currency": 840,
    "sign": "f97c52fa8d273a",
    "payway": "card_usd",
    "amount": 1,
    "shop_id": 112 
} 
```
Response 200 ()
- Body
```
{ 
"data": 
    { 
        "account_info_config"
        {
            "account": 
            {
                "regex": "\\d{9,15}$",
                "title": "79123456789"
            }
        }
        
        "payee_receive": 1,
        "ps_currency": 840,
        "shop_currency": 840,
        "shop_write_off": 1.02 
    }, 
    "error_code": 0, 
    "message": "Ok", 
    "result": true 
}  
```
- Attributes (object)
  - data (object, required) - Объект содержит данные о выплате
    - account_info_config (object, required) - Информация об аккаунте, на который будет выплата
      - account (object, required) - Дополнительная информация об аккаунте, на который будет выплата. Параметры в объекте могут отличаться для каждого направления на выплату
      - regex: \d15$ (string, required) - Регулярное выражение, которому должен соответствовать аккаунт
      - title: 79123456789 (string, required) - Название поля аккаунта
    - payee_receive: 1 (number, required) - Сумма выплаты, которая поступит на счет получателя в сторонней системе
    - ps_currency: 840 (number, required) - Валюта направления на выплату
    - shop_currency (number, required) - Валюта, в которой выплата спишется со счета магазина
    - write_off_amount (number, required) - Сумма списания с магазина в валюте кошелька
  - error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
  - message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
  - result: true (boolean, required) - Успешность запроса

Перевірка облікового запису check_account [/check_account]

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

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: account, payway, amount і shop_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Якщо у відповіді на запит Попередній розрахунок виплати повертається об'єкт account_info_config з додатковими параметрами, ці параметри, крім account, вам потрібно передавати в запиті на Створення виплати в параметрі account_details.

Приклад запиту

curl https://core.feennex.com/check_account \
   -H 'Content-Type: application/json' \
   -d '{
          "account": "4111111111111111",
          "account_details": {
              "contract": "C1234"
          },
          "sign": "faf7ee6db712752f2b107e05328bbd0d",
          "payway": "card_eur",
          "amount": 10.5,
          "shop_id": 1
       }'

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

Запросити перевірку [POST]

Request (application/json)
- Headers
- Attributes
  - account: 4111111111111111 (string, required) - Основной аккаунт, который нужно проверить на возможность пополнения. Формат для каждого платежного направления может отличаться: информацию можно уточнить в личном кабинете
  - account_details (object, optional) - Дополнительная информация для проверки аккаунта
    - contract: C1234 (string, optional) - Номер договора аккаунта, который нужно проверить на возможность пополнения
  - sign: 32b2c32caa8ad (string, required) - Подпись запроса
  - payway: card_usd (string, required) - Направление для выплаты. Возможные значения вы можете узнать в личном кабинете в настройках магазина в разделе Направления вывода. Валюта получения зависит от переданного направления для выплаты
  - amount: 1 (number, required) - Сумма планируемого зачисления на аккаунт в валюте платежного направления. Нужно для проверки лимитов пополнения
  - shop_id: 1 (number, required) - Идентификатор вашего магазина, с которого осуществляется выплата
- Body
```
{
    "account": "4111111111111111",
    "account_details": {
        "contract": "C1234"
    },
    "sign": "faf7ee6db712752f2b107e05328bbd0d",
    "payway": "card_eur",
    "amount": 10.5,
    "shop_id": 1
}
```
Response 200 ()
- Body
```
{
    "data": {
        "account_info": {
            "verified": "true"
        },
        "provider_status": 1,
        "result": true
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}
```
- Attributes (object)
  - data (object, required) - Объект содержит данные о проверке
    - account_info (object, required) - дополнительная информация, возвращаемая от провайдера услуги, можно отображать плательщику, так как зачастую содержит его персональную информацию, например, ФИО владельца аккаунта
      - verified: true (boolean, required) -
    - provider_status: 1 (number, required) - статус ответа провайдера, на запрос проверки возможности пополнения аккаунта, формат: 1 - провайдер доступен, проверка прошла без ошибок; 2 - ошибка на провайдере, результат проверки неизвестен; 3 - ошибка при обработке запроса, результат проверки неизвестен;
    - result: true (boolean, required) - результат проверки возможности пополнения на аккаунт
  - error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
  - message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
  - result: true (boolean, required) - Успешность запроса

Створення виплати withdraw/create [/withdraw/create]

Метод створює виплату для переказу грошей з балансу вашого магазину Feennex на доступні платіжні системи, крім гаманця Feennex.

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: account, amount, amount_type, payway, shop_currency, shop_id і shop_payment_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

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

Причину відхилення виплати ви можете знайти в параметрі rejected_reason, який повертається в запитах на створення виплати та отримання статусу виплати

Приклад запиту

curl https://core.feennex.com/withdraw/create \
   -H 'Content-Type: application/json' \
   -d '{
          "account": "4111111111111111",
          "amount": 1,
          "amount_type": "ps_amount",
          "email": "[email protected]",
          "payway": "card_usd",
          "shop_currency": 840,
          "shop_id": 112,
          "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f",
          "sign": "b4c3ca4b403bb"
       }'

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

POST Створити виплату [POST]

Request (application/json)
- Headers
- Attributes
  - account: 4111111111111111 (string, required) - Аккаунт получателя выплаты в платежной системе, например номер карты
  - amount: 1 (number, required) - Сумма получения или списания. Зависит от значения параметра amount_type
  - amount_type: ps_amount (string, required) - Определяет тип суммы. Возможные значения: ps_amount – сумма к получению в платежной системе, shop_amount – сумма к списанию с баланса вашего магазина
  - email: [email protected] (string, required) - Электронная почта получателя выплаты. Не участвует в формировании подписи
  - payway: card_usd (string, required) - Направление для выплаты. Возможные значения вы можете узнать в личном кабинете в настройках магазина в разделе Направления вывода. Валюта получения зависит от переданного направления для выплаты
  - shop_currency: 840 (number, required) - Валюта, в которой выплата спишется со счета вашего магазина. Возможные значения валют
  - shop_id: 1 (number, required) - Идентификатор вашего магазина, с которого осуществляется выплата
  - shop_payment_id (string, required) - Уникальный идентификатор выплаты на вашей стороне
  - sign: 32b2c32caa8ad (string, required) - Подпись запроса
  - account_details (object, optional) - Объект с дополнительной информацией об аккаунте получателя выплаты. Состав параметров в объекте зависит от выбранного направления для выплат. Список параметров можно посмотреть в личном кабинете по каждому направлению
  - description: Выплата (string, optional) - Описание выплаты. Значение передается в назначении платежа, если платежная система имеет такую функцию. Не более 255 символов
- Body
```
{
    "account": "4111111111111111",
    "amount": 1,
    "amount_type": "ps_amount",
    "email": "[email protected]",
    "payway": "card_usd",
    "shop_currency": 840,
    "shop_id": 112,
    "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f",
    "sign": "b4c3ca4b403bb" 
}
```
Response 200 ()
- Body
```
{
  "data": 
    {
        "balance": 0.0, 
        "id": 11298076, 
        "payee_receive": 1, 
        "ps_currency": 840, 
        "shop_currency": 840, 
        "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f", 
        "shop_write_off": 1.02, 
        "status": 3
     }, 
    "error_code": 0, 
    "message": "Ok", 
    "result": true
} 
```
- Attributes (object)
  - data (object, required) - Объект содержит данные о выплате
    - balance: 0.0 (number, required) - Баланс вашего магазина после успешного создания выплаты
    - id: 11298076 (number, required) - Уникальный идентификатор выплаты на стороне Feennex
    - payee_receive: 1 (number, required) - Сумма выплаты, которая поступит на счет получателя в сторонней системе
    - shop_currency: 840 (number, required) - Валюта, в которой выплата спишется со счета вашего магазина
    - shop_payment_id (string, required) - Уникальный идентификатор выплаты на вашей стороне
    - shop_write_off: 1.02 (number, required) - Cумма, которая спишется с вашего магазина
    - status: 3 (number, required) - Статус выплаты
  - error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
  - message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
  - result: true (boolean, required) - Успешность запроса

Запит статусу за ідентифікатором виплати withdraw/status [/withdraw/status]

Метод дозволяє отримати статус виплати за ідентифікатором виплати – параметром withdraw_id.

Рекомендується запитувати статус виплати не частіше, ніж раз на хвилину.

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: now, shop_id і withdraw_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/withdraw/status \
   -H 'Content-Type: application/json' \
   -d '{
          "now": "2024-12-06 16:07:28.878200",
          "shop_id": 112,
          "withdraw_id": 11298076,
          "sign": "e1dfc97b2c5430"
       }'

Приклад відповіді при помилці

{
  "error_code": 2000,
  "message": "Withdraw (id=3) wasn't found",
  "data": null,
  "result": false
}

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

POST Запитати статус виплати [POST]

Request (application/json)
- Headers
- Attributes
  - now (string, required) - Дата и время, когда вы отправляете запрос. Формат: ISO 8601
  - shop_id: 1 (number, required) - Идентификатор вашего магазина, с которого осуществляется выплата
  - withdraw_id: 112 (number, required) - Уникальные идентификатор выплаты на стороне Feennex, для которой необходимо узнать статус
  - sign: 32b2c32caa8ad (string, required) - Подпись запроса
- Body
```
{
    "now": "2024-12-06 16:07:28.878200",
    "shop_id": 112,
    "withdraw_id": 11298076,
    "sign": "e1dfc97b2c5430" 
} 
```
Response 200 ()
- Body
```
{
     "data": {
        "id": 11298076,
        "payee_receive": 1,
        "ps_currency": 840,
        "shop_currency": 840,
        "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f",
        "shop_write_off": 1.02,
        "status": 5
    }, 
    "result": True,
    "error_code": 0, 
    "message": "Ok"
}
```
- Attributes (object)
  - data (object, required) - Объект содержит данные о выплате
    - id: 11298076 (number, required) - Уникальный идентификатор выплаты на стороне Feennex
    - payee_receive: 1 (number, required) - Сумма выплаты, которая поступит на счет получателя в сторонней системе
    - ps_currency: 840 (number, required) - Валюта получения выплаты в платежной системе
    - rejected_reason: Номер карты не существует. Пожалуйста, проверьте правильность номера (string, optional) - Причина отмены выплаты
    - shop_currency: 840 (number, required) - Валюта, в которой выплата спишется со счета вашего магазина
    - shop_payment_id (string, required) - Уникальный идентификатор выплаты на вашей стороне
    - shop_write_off: 1.02 (number, required) - Сумма списания с вашего магазина
    - status: 5 (number, required) - Статус выплаты. Возможные значения статусов
  - error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
  - message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
  - result: true (boolean, required) - Успешность запроса

Запит статусу за номером виплати у вашій системі withdraw/shop_payment_status [/withdraw/shop_payment_status]

Метод дозволяє отримати статус виплати за номером виплати у вашій системі – параметром shop_payment_id.

Рекомендується запитувати статус виплати не частіше, ніж раз на хвилину.

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: now, shop_id і shop_payment_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/withdraw/shop_payment_status \
   -H 'Content-Type: application/json' \
   -d '{
          "shop_id":112,
          "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f",
          "now": "2024-12-06 16:07:28.878200",
          "sign": "a1ab593500a4"
       }'

Приклад відповіді при помилці

{
    "error_code": 2000, 
    "message": "Withdraw (id=3) wasn't found", 
    "data": None, 
    "result": False
}

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

POST Запитати статус виплати за ідентифікатором виплати у вашій системі [POST]

Request (application/json)
- Headers
- Attributes
  - shop_id: 1 (number, required) - Идентификатор вашего магазина, с которого проходит выплата
  - shop_payment_id (string, required) - Уникальный номер выплаты на вашей стороне
  - now (string, required) - Дата и время, когда вы отправляете запрос. Формат: ISO 8601
  - sign: 32b2c32caa8ad (string, required) - Подпись запроса
- Body
```
{
     "shop_id":112,
     "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f",
     "now": "2024-12-06 16:07:28.878200",
     "sign": "a1ab593500a4"
} 
```
Response 200 ()
- Body
```
{
     "data": {
        "id": 11298076,
        "payee_receive": 1,
        "ps_currency": 840,
        "shop_currency": 840,
        "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f",
        "shop_write_off": 1.02,
        "status": 5
    }, 
    "result": True,
    "error_code": 0, 
    "message": "Ok"
}
```
- Attributes (object)
  - data (object, required) - Объект содержит данные о выплате
    - id: 11298076 (number, required) - Уникальный идентификатор выплаты на стороне Feennex
    - payee_receive: 1 (number, required) - Сумма выплаты, которая поступит на счет получателя в сторонней системе
    - ps_currency: 840 (number, required) - Валюта выплаты в платежной системе
    - shop_currency: 840 (number, required) - Валюта, в которой выплата спишется со счета вашего магазина
    - shop_payment_id (string, required) - Уникальный номер выплаты на вашей стороне
    - shop_write_off: 1.02 (number, required) - Сумма списания со счета вашего магазина
    - status: 5 (number, required) - Актуальный статус выплаты. Возможные значения статусов
  - error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
  - message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
  - result: true (boolean, required) - Успешность запроса

Group Методи для роботи з магазином

Перед інтеграцією ознайомтеся з розділом Початок роботи з API

Запит балансу shop_balance [/shop_balance]

Метод дозволяє дізнатися баланс вашого магазину Feennex.

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: now і shop_id. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Баланс магазину складається з наступних значень:

available – Сума, яка доступна для виплат, за винятком rolling_reserve
frozen – Заморожена сума на балансі. Наприклад, для виплати, яка знаходиться в обробці
hold – Тимчасово утримана сума. Наприклад, при перевірці вхідного надходження

Приклад запиту

curl https://core.feennex.com/shop_balance \
   -H 'Content-Type: application/json' \
   -d '{
          "shop_id":112,
          "now": "2024-04-12T06:18:34.719Z",
          "sign": "77c6cc948751ee"
       }'

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

Запитати баланс [POST]

Request (application/json)
- Headers
- Attributes
  - shop_id: 1 (number, required) - Идентификатор вашего магазина, с которого проходит выплата
  - shop_payment_id (string, optional) - Идентификатор транзакции на стороне магазина
  - now (string, required) - Дата и время, когда вы отправляете запрос. Формат: ISO 8601
  - sign: 32b2c32caa8ad (string, required) - Подпись запроса
- Body
```
{
    "now": "2024-04-12T06:18:34.719Z",
    "shop_id": 112,
    "sign": "77c6cc948751ee" 
}   
```
Response 200 ()
- Body
```
{
    "data": {
        "balances": [
            {
                "available": 100.0,
                "currency": 978,
                "frozen": 0.0,
                "hold": 0.0,
                "rolling_reserve": 0.0
            },
            {
                "available": 200.0,
                "currency": 840,
                "frozen": 0.0,
                "hold": 0.0,
                "rolling_reserve": 0.0
            },
            {
                "available": 93.0,
                "currency": 840,
                "frozen": 0.0,
                "hold": 0.0,
                "rolling_reserve": 0.0
            }
        ],
        "shop_id": 112
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}
```
- Attributes (object)
  - data (object, required) - Объект содержит информацию о балансе
    - balances (array, required) - баланс магазина в разрезе валют
      - object
        
        available: 93.0 (number, required) - Доступный баланс магазина
        
        currency: 840 (number, required) - Валюта баланса. Возможные значения валют
        
        hold: 0.0 (number, required) - Временно удержанные средства, например, при проверке входящего поступления
        
        frozen: 20.0 (number, required) - Замороженные средства на балансе магазина
        
        rolling_reserve 0.0 (number, optional) - Временно удержанные денежные средства на балансе магазина
    - shop_id: 112 (number, required) - Идентификатор вашего магазина Feennex
  - error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
  - message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
  - result: true (boolean, required) - Успешность запроса

Отримання доступних платіжних напрямків shop_input_config/shop [/shop_input_config/shop]

Метод повертає доступні для вашого магазину платіжні напрямки. Наприклад, оплата банківською карткою або гаманцем Feennex.

Для методу потрібно сформувати підпис за допомогою обов'язкових параметрів запиту: now і shop_id*. Сформований підпис потрібно передати в параметрі sign.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/shop_input_config/shop \
   -H 'Content-Type: application/json' \
   -d '{
          "shop_id":112,
          "now": "2024-04-12T06:18:34.719Z",
          "sign": "77c6cc948751ee"
       }'

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

POST Отримати доступні платіжні напрямки [POST]

Request (application/json)
- Headers
- Attributes
  - now (string, required) - Дата и время, когда вы отправляете запрос. Формат: ISO 8601
  - shop_id: 112 (number, required) - Идентификатор магазина, с которого осуществляется выплата
  - sign: 32b2c32caa8ad (string, required) - Подпись запроса
- Body
```
{
    "now": "03.09.2024 11:19:55",
    "shop_id": 3,
    "sign": "588485c9d7f0d"
}
```

Response 200 ()

Body

{
    "data": [
        {
            "id": 1,
            "is_bill_config": true,
            "name": "Feennex Wallet",
            "payways": [
                {
                    "alias": "feennex_usd",
                    "currency": 840,
                    "fee_config": {
                        "fix": 0,
                        "percent": 7
                    },
                    "fee_part_config": {
                        "fix_part": 1,
                        "percent_part": 1
                    },
                    "id": 83543,
                    "is_active": true,
                    "max_amount": 1000000,
                    "min_amount": 1
                }
            ],
            "rating": 1
        },
        {
            "id": 267,
            "name": "СБП h2h",
            "payways": [
                {
                    "add_ons_config": {
                        "email": {
                            "example": "[email protected]",
                            "label": {
                                "en": "E-mail:",
                                "ru": "E-mail:",
                                "uk": "E-mail:"
                            },
                            "regex": "^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$",
                            "title": {
                                "en": "Enter your Email",
                                "ru": "Введите Ваш Email",
                                "uk": "Введіть Ваш Email"
                            }
                        }
                    },
                    "alias": "sbp_h2h_usd",
                    "currency": 840,
                    "fee_config": {
                        "fix": 0,
                        "percent": 10
                    },
                    "fee_part_config": {
                        "fix_part": 0,
                        "percent_part": 1
                    },
                    "id": 797,
                    "is_active": true,
                    "max_amount": 100000,
                    "min_amount": 300
                }
            ],
            "rating": 94
        },
        {
            "id": 268,
            "name": "Банк h2h",
            "payways": [
                {
                    "add_ons_config": {
                        "email": {
                            "example": "[email protected]",
                            "label": {
                                "en": "E-mail:",
                                "ru": "E-mail:",
                                "uk": "E-mail:"
                            },
                            "regex": "^[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$",
                            "title": {
                                "en": "Enter your e-mail",
                                "ru": "Введите Ваш e-mail",
                                "uk": "Введіть Ваш e-mail"
                            }
                        }
                    },
                    "alias": "bank_h2h_usd",
                    "currency": 840,
                    "fee_config": {
                        "fix": 0,
                        "percent": 10
                    },
                    "fee_part_config": {
                        "fix_part": 0,
                        "percent_part": 1
                    },
                    "id": 798,
                    "is_active": true,
                    "max_amount": 100000,
                    "min_amount": 300
                }
            ],
            "rating": 95
        },
        {
            "id": 119,
            "name": "Банковские карты РФ",
            "payways": [
                {
                    "add_ons_config": null,
                    "alias": "card_rub",
                    "currency": 643,
                    "fee_config": {
                        "fix": 0,
                        "percent": 15
                    },
                    "fee_part_config": {
                        "fix_part": 0,
                        "percent_part": 1
                    },
                    "id": 864,
                    "is_active": true,
                    "max_amount": 140000,
                    "min_amount": 300
                }
            ],
            "rating": 108
        }
    ],
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Attributes (object)
- data (object, required) - Объект содержит данные о доступных платежных направлениях
  - object
    - id: 3 (number, required) - Идентификатор платежного метода
    - is_bill_config (boolean, optional) - Параметр, который указывает, что направление предназначено для платежей
    - name: MIR (string, required) - Наименование платежного метода
    - payways (array, required) - Платежные направления, которые включены магазину
      - object
        
        add_ons_config (string, optional) - Дополнительная информация, если она требуется по платежному направлению
        
        alias: card_usd (string, required) - Наименование платежного направления
        
        currency: 840 (number, required) - Валюта в разрезе платежного направления. Возможные значения валют
        
        fee_config (object) - настройки распределения комисии между магазином и плательщиком
        
        fix: 0.0 (number, required) - фиксированная комиссия
        
        percent: 6.0 (number, required) - распределение процентной комиссии (0,0-1,0)
        
        fee_part_config (object, optional) - настройки распределения комисии между магазином и плательщиком
        
        fix: 0.0 (number, required) - фиксированная комиссия
        
        percent: 6.0 (number, required) - процентная комиссия
        
        id: 154 (number, required) - Id платежного направления
        
        is_active: true (boolean, required) - статус активации
        
        max_amount: 100000.0 (number, required) - максимальная сумма платежа в разрезе направления
        
        min_amount: 1.0 (number, required) - минимальная сумма платежа в разрезе направления
    - rating (number, optional) - Служебный параметр
- error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
- message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
- result: true (boolean, required) - Успешность запроса

Отримання доступних напрямків для виплат shop_output_config/shop [/shop_output_config/shop]

Метод повертає доступні для вашого магазину напрямки для виплат. Наприклад, виплата на банківську картку.

Натисніть на кнопку в кінці опису методу, щоб побачити опис параметрів запиту і відповіді.

Приклад запиту

curl https://core.feennex.com/shop_output_config/shop \
   -H 'Content-Type: application/json' \
   -d '{
          "shop_id":3,
          "now": "03.09.2024 11:19:55",
          "sign": "588485c9d7f0d"
       }'

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

POST Отримати доступні напрямки для виплат [POST]

Request (application/json)
- Headers
- Attributes
  - now (string, required) - Дата и время, когда вы отправляете запрос. Формат: ISO 8601
  - shop_id: 1 (number, required) - Идентификатор вашего магазина, с которого проходит выплата
  - sign: 32b2c32caa8ad (string, required) - Подпись запроса
- Body
```
{
    "now": "03.09.2024 11:19:55",
    "shop_id": 3,
    "sign": "588485c9d7f0d"
}
```

Response 200 ()

Body

{
    "data":[
       {
            "id": 1,
            "name": "MIR",
            "payways": [
            {
                "account_info_config":
                {
                    "account":
                    {
                        "regex": "^(4|5|6)[0-9]{15,17}$",
                        "title": "Номер карты"
                    }
               },
               "alias":"card_eur",
               "currency": 978,
               "fee_config":
               {
                  "fix": 10.0,
                  "percent": 1.5
               },
               "info_id": null,
               "max_amount": 14999.0,
               "min_amount": 1.0
               }
            ],
            "rating": 1
        },
        {
            "id": 3,
            "is_transfer_config": true,
            "name": "Feennex",
            "payways": [
            {
               "account_info_config": 
               {
                  "payee_account": {
                     "regex": "^20[\\d]{10}$|^([a-zA-Z0-9_-]+\\.)*[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*\\.[a-zA-Z]{2,6}$",
                     "title": "Номер кошелька или email"
                  }
               },
               "alias": "feennex_usd",
               "currency": 840,
               "fee_config":
               {
                  "fix": 0.0,
                  "percent": 0.0
               },
               "info_id": null,
               "max_amount": 10000.0,
               "min_amount": 0.5
               }
            ],
            "rating": 22
        }
        ],
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Attributes (object)
- data (object, required) - Объект содержит данные о доступных направлениях для выплат
  - id: 3 (number, required) - Идентификатор платежного метода
  - is_transfer_config (boolean, optional) - Параметр, который указывает, что направление предназначено для выплат
  - name: MIR (string, required) - Наименование платежного метода
  - payways (array, required) - Направления для выплат, которые подключены для вашего магазина
    - object
      - account_info_config (object) - Информация об аккаунте, на который будет выплата
        
        account (object) - Дополнительная информация об аккаунте
        
        regex (string, required) - Регулярное выражение, которому должен соответствовать аккаунт
        
        title (string, required) - Название поля аккаунта
    - alias: card_usd (string, required) - наименование платежного направления
    - currency: 840 (number, required) - валюта в разрезе платежного направления. Возможные значения валют
    - fee_config (object) - Размер комиссии
      - fix: 0.0 (number, required) - фиксированная комиссия
      - percent: 6.0 (number, required) - процентная комиссия
    - info_id: null (string, required) - служебный параметр
    - max_amount: 10000.0 (number, required) - максимальная сумма платежа в разрезе направления
    - min_amount: 0.5 (number, required) - минимальная сумма платежа в разрезе направления
  - rating: 22 (number, required) - Служебный параметр
- error_code: 0 (number, required) - Код ошибки. Возможные значения кодов ошибок
- message: Ok (string, required) - Описание ошибки. По значению этого параметра можно определить успешность запроса и узнать, что пошло не так
- result: true (boolean, required) - Успешность запроса

Запит доступності сервісу Feennex check_status [/check_status]

Метод дозволяє дізнатися доступність сервісу Feennex.

Приклад запиту

curl -X GET \ 
--location 'https://core.feennex.com/check_status' \

Натисніть на кнопку нижче, щоб переглянути параметри методу та тіла запиту і відповіді.

GET Запитати доступність сервісу [GET]

Headers
Content-Type: application/json

Request

{
    https://core.feennex.com/check_status
}

Response 200 ()
- Body
```
{
    "status": "OK"
}
```
- Attributes (object)
  - status: ОК (string, required) - Статус доступности сервиса

Group Коди помилок

Код помилки повертається у відповіді в параметрі error_code.

Приклад відповіді при помилці

{
    "data": null,
    "error_code": 5,
    "message": "Payer price amount is too large, max: 100000.0",
    "result": false
}

Можливі коди помилок

The payment has been declined. Please try entering another amount without «0» at the end. For example: 347, 1832, 5783.", "ru": "Платеж отклонен. Попробуйте ввести неровную сумму без «0» на конце. Пример: 347, 1832, 5783"

Код помилки	Опис	Приклад повідомлення про помилку
1	PaywayNotFound: Платіжний напрямок відключено: в налаштуваннях ПН відключена опція Статус
2	PaywayNotUsed: Платіжний напрямок не використовується
3	PaywayNotAvailable: Платіжний напрямок недоступний	Payway (alias = card_usd) is not available for shop
4	AmountTooSmall: Сума занадто мала
5	AmountTooLarge: Сума занадто велика
6	OperationNotUnique: Операція з переданим ідентифікатором вже існує в системі
7	OperationNotFound: Операція не знайдена	Withdraw (id=1234567) wasn't found
8	OperationIsProcessing: У операції значення поля `processing` дорівнює true. Це відбувається, коли зовнішня система запитує інформацію по операції при повторному опитуванні статусу у провайдера
9	InsufficientBalance: Недостатній баланс для виконання операції	Insufficient balance(currency=840): shop_write_off=500.0, balance=0.0
10	IncorrectRequestParam: Некоректний параметр запиту	Invalid sign, string_to_sign: 500:840:bank_h2h_usd:6199:99991
11	ShopNotFound: Магазин не знайдено
12	ShopNotActive: Магазин неактивний
13	AccountNotFound: Обліковий запис з переданим ідентифікатором не знайдено в базі даних Feennex
14	IncorrectAccountStatus: Некоректний статус облікового запису
15	RequestIpDenied: IP-адресу запиту відхилено	Shop ip 111.111.111.111 denied
16	InvalidCurrencyExchange: Не вдалося конвертувати суму: немає інформації по курсу обміну або задано невірний курс, наприклад 0
17	InvalidShopContract: У магазину немає контракту на проведення операцій вказаного типу
18	IncorrectAccountType: Цей тип акаунта (персональний або бізнес) не може провести вказану операцію
19	ShopAggregatorRequire: У магазину налаштування `is_aggregator` має значення false
20	Застаріла
21	Застаріла
27	DailyLimitExceeds. Перевищено денний ліміт на виплату
33	WeekLimitExceeds: Перевищено тижневий ліміт на виплату
34	MonthLimitExceeds: Перевищено місячний ліміт на виплату
41	Сума не відповідає заданому для ПН регулярному виразу	"en": "
100	IncorrectOperationStatus: Неможливо обробити операцію з поточним статусом
2000	Інша помилка, яка не входить в інші категорії	Service error

Group Можливі статуси

Якщо платіж або виплата успішно створені, у відповіді Feennex поверне унікальний ідентифікатор і статус операції. Платежі та виплати мають різні статуси.

Статус може бути фінальним і нефінальним. Продовжуйте запитувати статус, поки не повернеться один із фінальних статусів.

Статуси платежів відрізняються залежно від того, для якого способу оплати ви створювали платіж:

гаманець Feennex
сторонні способи оплати

Статуси платежу при оплаті з гаманця Feennex

Статус	Значення	Опис
1	`Waiting`	Платіж знаходиться на стадії очікування дій користувача
2	`Paid`	Платіж оплачений клієнтом. Фінальний статус
3	`Canceled`	Платіж скасований клієнтом. Фінальний статус
4	`Expired`	Закінчився строк життя рахунку. Фінальний статус

Статуси платежу при оплаті сторонніми способами оплати

Статус	Значення	Опис
1	`Created`	Платіж створено та очікує обробки
2	`Waiting`	Платіж знаходиться на стадії очікування дій користувача
3	`PsCreatingError`	Помилка створення платежу на стороні платіжної системи
4	`Success`	Оплату пройшло. Фінальний статус
5	`CallbackError`	Застарів. Не використовується для нових платежів
6	`PsRejected`	Відхилено на стороні платіжної системи. Фінальний статус
7	`Refunded`	Сума рахунку повернена платнику платіжною системою. Фінальний статус
8	`Hold`	Від платіжної системи отримано колбек з неуспішним статусом платежу, крім Recalculated
9	`pspRefunded`	Сума рахунку повернена платнику системою Feennex. Фінальний статус
10	`Captured`	Кошти по оплаті рахунку заблоковані платіжною системою
11	`Refunding`	Кошти по оплаті рахунку в процесі повернення: відправлено запит в платіжну систему на повернення коштів
12	`Recalculated`	Сума по оплаті рахунку була перерахована. Фінальний статус. Користувач при оплаті рахунку відправив іншу суму замість тієї, яка була вказана при створенні рахунку. Детальніше про дії при невірній сумі платежу

Статуси виплат

Статуси у виплатах відрізняються залежно від того, куди переказуються гроші.

Статуси виплат на гаманець Feennex

Виплата на гаманець не має статусу. Якщо у відповіді повертається параметр id (унікальний ідентифікатор виплати), це означає, що виплата пройшла. Вам не потрібно додатково запитувати статус виплати.

Статуси виплат на рахунок у сторонній системі

Якщо виплата успішно створена, то у відповіді буде повернуто унікальний ідентифікатор виплати та її статус.

Статус може бути фінальним і нефінальним. Продовжуйте запитувати статус платежу, поки не отримаєте один із фінальних статусів.

Статус	Значення	Опис
1	`Created`	Виплату створено та очікує обробки
2	`WaitingManualConfirmation`	Виплата вимагає ручного підтвердження з боку оператора
3	`PsProcessing`	Виплату відправлено в платіжну систему
4	`PsProcessingError`	Помилка при виплаті на стороні платіжної системи. Спробуйте запросити статус пізніше або зверніться в підтримку
5	`Success`	Виплату завершено. Гроші списано з рахунку вашого магазину. Фінальний статус
6	`Rejected`	Відхилено на стороні платіжної системи. Кошти не списано з рахунку магазину. Фінальний статус
7	`ManualConfirmed`	Виплату підтверджено оператором та очікує проведення
9	`PsNetworkError`	Мережева помилка на стороні платіжної системи
10	`CanceledManually`	Вивід скасовано на стороні системи Feennex в ручному режимі. Фінальний статус
11	`Refunded`	Вивід завершився успішно

Статуси чеків

Зверніть увагу! Чеки потрібні тільки для способу оплати Переказ на банківський рахунок, коли платник провів оплату, а статус платежу не змінився.

Чек, який ви передали в технічну підтримку за допомогою методу Відправка чеків, може мати один з наступних статусів:

Статус	Опис
`pending`	Чек отримано та перевіряється.
`succeed`	Чек успішно перевірено. Статус не говорить про те, що переказ пройшов.
`rejected`	Перевірка чека не пройшла.

Щоб дізнатися статус чека, періодично відправляйте запити на Отримання статусу чека

Group Доступні валюти

У таблиці наведені основні валюти, які підтримує Feennex. Для кожної валюти вказано код за стандартом ISO-4217. Повний список валюти, що підтримуються, вам надасть менеджер.

Код	Назва валюти
398	Казахстанський тенге
417	Киргизький сом
643	Російський рубль
840	Долар США
860	Узбецький сум
944	Азербайджанський манат
949	Турецька ліра
978	Євро
980	UAH

Group Терміни

Термін	Опис
Переказ на банківський рахунок	Сторонній спосіб оплати, коли платник поповнює вказаний на сторінці оплати банківський рахунок
Feennex	Feennex — рішення для електронних платежів, що дозволяє приймати платежі та проводити виплати
Мерчант	Учасник, який приймає платежі
Платник	Учасник, який проводить оплату
Платіж	Одна з основних сутностей. Feennex API. Платіж потрібен для проведення платежів. Містить статус, за яким можна дізнатися, в якому стані знаходиться платіж. Детальніше про статуси платежів
Платіжний напрямок	Шлях, яким проходить платіж. Кожен напрямок має власні ліміти та підтримувану валюту
Виплата	Одна з основних сутностей Feennex API. Виплата потрібна для переказу грошей з рахунку магазину вашим клієнтам
Платіжна сторінка	Сторінка, на якій платник проводить оплату. Якщо ви використовуєте самостійну інтеграцію, цю сторінку потрібно реалізувати самостійно

Group Логотипи Feennex

Feennex Logo

В репозитории все 3 варианта логотипа в форматах .png

Group Історія змін API

Дата	Подія
27.02.2025	Зміни для способу оплати Переказ на банківський рахунок. Тепер Feennex може пропонувати платнику переказати рекомендовану суму. Переказ рекомендованої суми підвищить швидкість зарахування коштів. Якщо ви використовуєте Самостійну інтеграцію, вам потрібно доопрацювати вашу систему. Для інших сценаріїв інтеграції робити нічого не потрібно.
16.01.2025	Feennex тимчасово відправляє вхідні сповіщення (callback) у форматі raw data замість JSON
10.12.2024	Додано нову причину помилки 41, яка повертається, якщо сума операції не відповідає регулярному виразу. Цей вираз задається в адміністративній панелі в розділі Платіжні системи > Управління ПН
27.11.2024	Оновлено список IP-адрес, з яких Feennex може надсилати сповіщення
02.10.2024	Запуск нової документації

Group Контакти

Якщо у вас залишилися питання, зверніться до менеджера або на [email protected]

Вступ
- Про прийом платежів
- Про виплати
Формaт взаємодії
- Основи
- Oбрoбкa відповідей
Вxідні сповіщення
- Основи
- Підключення сповіщень
- Використання
- Перевірка справжності сповіщень
- Відповідь на сповіщення
- Приклади сповіщень
- Параметри сповіщення
Початок роботи з API
- Підключення
- Створення акаунта і магазину Feennex
- Підтвердження магазину
- Налаштування безпеки
- Формування підпису
- Інтеграція з Feennex по API
Вибір сценарію інтеграції
Сценарій Платіжна сторінка Feennex
- Основи
- Особливості
- Формування HTML-форми
Сценарій Створення платежу (редиректний)
- Оплата гаманцем Feennex
- Оплата іншими способами
Сценарій Самостійна інтеграція Host-to-Host
- Оплата банківською карткою
- Оплата переказом на банківський рахунок
Після оплати
- Повернення
- Неправильна сума оплати
- Платник здійснив оплату переказом на банківський рахунок, але статус не змінюється
- Неуспішна оплата
- Реєстри
Про виплати
- Як проходять виплати
- Способи отримання виплат
- Виплати на гаманці Feennex
- Виплати на сторонні платіжні системи
Group Прийом платежів: гаманець Feennex
- Створення платежу з оплатою гаманцем bill/create [/bill/create]
- POST Створити платіж для оплати гаманцем [POST]
- Запит статусу платежу при оплаті гаманцем bill/shop_order_status [/bill/shop_order_status]
- POST Запитати статус платежу при оплаті гаманцем [POST]
Group Прийом платежів: сторонні платіжні системи
- Попередній розрахунок платежу invoice/try [/invoice/try]
- Розрахувати платіж [POST]
- Створення платежу invoice/create [/invoice/create]
- POST Створити платіж [POST]
- Запит статусу платежу invoice/check [/invoice/check]
- POST Запит статусу платежу [POST]
- Дані для HTML-форми [/h2h_data]
- POST Запит даних для HTML-форми [POST]
Надсилання чеків order/{id}/receipt [/api/v1/order/{id}/receipt]
POST Надіслати чек [POST]
Отримання статусу чека order/{id}/receipt/status [/api/v1/order/{id}/receipt/status]
GET Отримати статус чека [GET]
Group Виплата на гаманець Feennex
- Попередній розрахунок виплати на гаманець Feennex transfer/try [/transfer/try]
- POST Попередній розрахунок виплати [POST]
- Виплата на гаманець Feennex transfer/create [/transfer/create]
- Створення виплати на гаманець [POST]
- Запит статусу виплати на гаманець transfer/shop_payment_status [/transfer/shop_payment_status]
- Запитати статус виплати на гаманець [POST]
Group Виплата на рахунок у сторонній платіжній системі
- Попередній розрахунок виплати withdraw/try [/withdraw/try]
- Запитати розрахунок виплати [POST]
- Перевірка облікового запису check_account [/check_account]
- Запросити перевірку [POST]
- Створення виплати withdraw/create [/withdraw/create]
- POST Створити виплату [POST]
- Запит статусу за ідентифікатором виплати withdraw/status [/withdraw/status]
- POST Запитати статус виплати [POST]
- Запит статусу за номером виплати у вашій системі withdraw/shop_payment_status [/withdraw/shop_payment_status]
- POST Запитати статус виплати за ідентифікатором виплати у вашій системі [POST]
Group Методи для роботи з магазином
- Запит балансу shop_balance [/shop_balance]
- Запитати баланс [POST]
- Отримання доступних платіжних напрямків shop_input_config/shop [/shop_input_config/shop]
- POST Отримати доступні платіжні напрямки [POST]
- Отримання доступних напрямків для виплат shop_output_config/shop [/shop_output_config/shop]
- POST Отримати доступні напрямки для виплат [POST]
- Запит доступності сервісу Feennex check_status [/check_status]
- GET Запитати доступність сервісу [GET]
Group Коди помилок
Group Можливі статуси
- Статуси платежу при оплаті з гаманця Feennex
- Статуси платежу при оплаті сторонніми способами оплати
- Статуси виплат
- Статуси чеків
Group Доступні валюти
Group Терміни
Group Логотипи Feennex
Group Історія змін API
Group Контакти

Вступ​

Про прийом платежів​

Про виплати​

Формaт взаємодії​

Основи​

Oбрoбкa відповідей​

Формат відповіді​

Тіло відповіді при успіху​

Вxідні сповіщення​

Основи​

Оплата гаманцем Feennex​

Платіж при оплаті сторонніми способами оплати​

Підключення сповіщень​

Використання​

Перевірка справжності сповіщень​

Відповідь на сповіщення​

Приклади сповіщень​

Сповіщення при успіху​

Сповіщення при невдачі​

Параметри сповіщення​

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

Підключення​

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

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

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

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

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

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

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

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

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

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

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

Вибір сценарію інтеграції​

Сценарій Платіжна сторінка Feennex​

Основи​

Особливості​

Формування HTML-форми​

Приклад HTML-форми​

Параметри платіжної форми​

URL-адреса для надсилання форми​

Параметри форми​

Сценарій Створення платежу (редиректний)​

Оплата гаманцем Feennex​

Оплата іншими способами​

Сценарій Самостійна інтеграція Host-to-Host​

Оплата банківською карткою​

Крок 1. Створення платежу​

Крок 2. Отримання токена та URL-адреси​

Крок 3. Формування платіжної форми​

Збір даних банківської картки платника​

Відправлення запиту на створення HTML-форми​

Крок 4. Перенаправлення платника на HTML-форму​

Оплата переказом на банківський рахунок​

Крок 1. Створення платежу​

Крок 2. Отримання даних для переказу​

Крок 3. Запит статусу платежу​

Після оплати​

Повернення​

Неправильна сума оплати​

Недостатня оплата​

Переплата​

Платник здійснив оплату переказом на банківський рахунок, але статус не змінюється​

Крок 1. Реалізація сторінки завантаження чека​

Крок 2. Запит статусу платежу​

Крок 4. Відображення інформації про статус чека​

Неуспішна оплата​

Реєстри​

Підписка на розсилку реєстрів​

Поля в реєстрі​

Приклад реєстру​

Про виплати​

Як проходять виплати​

Способи отримання виплат​

Виплати на гаманці Feennex​

Сценарій проведення виплати на гаманці Feennex​

Виплати на сторонні платіжні системи​

Group Прийом платежів: гаманець Feennex​

Створення платежу з оплатою гаманцем bill/create [/bill/create]​

POST Створити платіж для оплати гаманцем [POST]​

Вступ

Про прийом платежів

Про виплати

Формaт взаємодії

Основи

Oбрoбкa відповідей

Формат відповіді

Тіло відповіді при успіху

Вxідні сповіщення

Основи

Оплата гаманцем Feennex

Платіж при оплаті сторонніми способами оплати

Підключення сповіщень

Використання

Перевірка справжності сповіщень

Відповідь на сповіщення

Приклади сповіщень

Сповіщення при успіху

Сповіщення при невдачі

Параметри сповіщення

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

Підключення

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

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

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

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

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

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

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

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

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

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

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

Вибір сценарію інтеграції

Сценарій Платіжна сторінка Feennex

Основи

Особливості

Формування HTML-форми

Приклад HTML-форми

Параметри платіжної форми

URL-адреса для надсилання форми

Параметри форми

Сценарій Створення платежу (редиректний)

Оплата гаманцем Feennex

Оплата іншими способами

Сценарій Самостійна інтеграція Host-to-Host

Оплата банківською карткою

Крок 1. Створення платежу

Крок 2. Отримання токена та URL-адреси

Крок 3. Формування платіжної форми

Збір даних банківської картки платника

Відправлення запиту на створення HTML-форми

Крок 4. Перенаправлення платника на HTML-форму

Оплата переказом на банківський рахунок

Крок 1. Створення платежу

Крок 2. Отримання даних для переказу

Крок 3. Запит статусу платежу

Після оплати

Повернення

Неправильна сума оплати

Недостатня оплата

Переплата

Платник здійснив оплату переказом на банківський рахунок, але статус не змінюється

Крок 1. Реалізація сторінки завантаження чека

Крок 2. Запит статусу платежу

Крок 4. Відображення інформації про статус чека

Неуспішна оплата

Реєстри

Підписка на розсилку реєстрів

Поля в реєстрі

Приклад реєстру

Про виплати

Як проходять виплати

Способи отримання виплат

Виплати на гаманці Feennex

Сценарій проведення виплати на гаманці Feennex

Виплати на сторонні платіжні системи

Group Прийом платежів: гаманець Feennex

Створення платежу з оплатою гаманцем bill/create [/bill/create]

POST Створити платіж для оплати гаманцем [POST]