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

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

Перед интеграцией ознакомьтесь с разделом Началo работы с 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-адрес в запросе, удалите значение соответствущий адрес из настроек магазина
  - callback_rejected_url (string, optional) - URL-адрес, на который отправляется уведомление о неуспешной оплате. Если хотите передавать URL-адрес в запросе, удалите значение соответствущий адрес из настроек магазина
- 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/&#123;id&#125;/receipt [/api/v1/order/{id}/receipt]​

POST Отправить чек [POST]​

Получение статуса чека order/&#123;id&#125;/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]