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

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.

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

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

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

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 Прийом платежів: сторонні платіжні системи​

Попередній розрахунок платежу 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 Прийом платежів: сторонні платіжні системи

Попередній розрахунок платежу 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]