Payment via External Systems

Group Payment via third-party payment systems

Before integration, please read the Get started with API section.

Payment precalculation [/invoice/try]

This endpoint is optional. It returns additional information for creating a payment with a preliminary calculation of the commission.

To use this method, you need to generate a signature using the required request parameters: shop_id, amount, currency, payway, and shop_order_id. The generated signature must be passed in the sign parameter.

Click the button at the end of the method description to view the request and response parameter details.

Example request

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
       }'

Example response in case of an error

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

Click the button below to view the endpoint parameters and request/response bodies.

Precalculate payment [POST]

Headers
Content-Type: application/json
Request (application/json)
- Attributes
  - shop_id: 5 (number, required) - Your shop's identifier in Feennex
  - amount: 100 (number, required) - Payment amount
  - currency: 840 (number, required) - Payment currency. Possible currency values
  - payway: card_usd (string, required) - Payment direction for which the calculation is performed. Possible values can be found in your personal account under the shop settings in the Payment Methods section.
  - sign: a7f5bcbb774ce (string, required) – Request signature
  - shop_order_id (string, required) - Unique order number in your system. No more than 255 characters
  - description: Payment for order (string, optional) – Payment description. No more than 255 characters
- 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": 643,
        "warning": null
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Attributes (object)
- data (object, required) - Object contains data about the preliminary payment calculation
  - add_ons_config (object, required) - Additional information if required by the payment direction
  - exch_fee: 0 (number, required) - Commission for conversion
  - info: null (string, required) - Additional payment information
  - manual: 1 (number, required) - Service parameter
  - payer_fee: 0 (number, required) - Commission amount
  - payer_price: 500 (number, required) - Amount the payer should pay. Includes Feennex commission
  - paymethod_id: 268 (number, required) - Payment direction identifier
  - paymethod_name: Bank h2h (string, required) - Payment direction name
  - ps_currency: 840 (number, required) - Currency received in the payment system
  - warning: null (string, required) - Service parameter
- error_code: 0 (number, required) - Error code. Possible error codes
- message: Ok (string, required) - Contains error description. Example: Ok. Based on this parameter's value, you can determine the success of the request and find out what went wrong
- result: true (boolean, required) - Success of the request

Create payment [/invoice/create]

Use this endpoint to receive payments through any means except Feennex Wallets.

Important! If you want to accept payment using a Feennex Wallet, create a payment using the Create payment when paying with Wallet endpoint.

To use this method, you need to generate a signature using the required request parameters: shop_id, amount, email, currency, payway, and shop_order_id. The generated signature must be passed in the sign parameter.

Click the button at the end of the method description to view the request and response parameter details.

Example request

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": "Payment for order #123"
       }'

Example response in case of an error

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

Click the button below to view the endpoint parameters and request/response bodies.

POST Create payment [POST]

Request (application/json)
- Attributes
  - shop_id: 5 (number, required) - Your shop's identifier in Feennex
  - amount: 100 (number, required) - Payment amount
  - email: [email protected] (string, required) - Payer's email. The parameter isn't involved in generating the signature
  - currency: 840 (number, required) - Currency of the payment. Possible currency values
  - payway: card_rub (string, required) - Payment direction. Possible values can be found in your personal account under the shop settings in the Payment Methods section
  - sign (string, required) – Request signature
  - shop_order_id (string, required) - Unique order number in your system. No more than 255 characters
  - description: Payment for order (string, optional) – Payment description. No more than 255 characters
  - failed_url: https://feennex.com/failed (string, optional) - URL to which the payer is redirected after a failed payment. If you want to pass the URL in the request, remove the corresponding address from the shop settings in the dashboard
  - success_url: https://feennex.com/success (string, optional) - URL to which the payer is redirected after a successful payment. If you want to pass the URL in the request, remove the corresponding address from the shop settings in the dashboard
  - callback_url (string, optional) - URL to which a notification of successful payment is sent. If you want to pass the URL in the request, remove the corresponding address from the shop settings in the dashboard
  - callback_rejected_url (string, optional) - URL to which a notification of failed payment is sent. If you want to pass the URL in the request, remove the corresponding address from the shop settings in the dashboard
- Body
```
{
    "currency": "840",
    "payway": "card_usd",
    "amount": "12.34",
    "email": "[email protected]",
    "shop_id": 112,
    "shop_order_id": 4129,
    "description": "Payment for order #123" ,
    "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) - Object contains information about the payment
    - data (object, required) - Payment data
      - session_id (string, optional) - Session identifier. Returned if you passed card-rub in the payway parameter
      - language: en (string, optional) - Service parameter
      - mdOrder (string, optional) - Service parameter
    - method: GET (string, required) - Type of request to redirect the payer to the URL specified in the url parameter
    - url: https://epg.guavapay.com/epg/merchants/Skillgurus_PSX/payment.html (string, required) - URL to which the payer should be redirected
    - id: 489222674 (number, required) - Unique identifier of the payment in Feennex
  - error_code: 0 (number, required) - Error code. Possible error codes
  - message: Ok (string, required) - Error description. Based on this parameter's value, you can determine the success of the request and find out what went wrong
  - result: true (boolean, required) - Success of the request

Request payment status [/invoice/check]

Use this endpoint to check the status of a created payment if the payer used any available payment methods, except Feennex Wallets.

Important! To check the status of a payment you created for wallet payment, use the Request payment status when paying with Wallet endpoint.

To use this method, you need to generate a signature using the required request parameters: now, shop_id, and shop_order_id. The generated signature must be passed in the sign parameter.

Click the button at the end of the method description to view the request and response parameter details.

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" 
       }'

Click the button below to view the endpoint parameters and request/response bodies.

POST Request payment status [POST]

Request (application/json)
- Attributes
  - now (string, required) - Date and time when you send the request. Format: ISO 8601
  - shop_id: 1 (number, required) - Your shop's identifier in Feennex
  - shop_order_id: "123456789" (string, required) - Unique order number in your system. No more than 255 characters
  - sign: 32b2c32caa8ad (string, required) - Request signature
- 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":"Payment for order #123",
      "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) - Object contains information about the payment
    - client_price: 1000.2 (number, required) - Actual amount paid by the payer
    - created: 2024-04-10 12:59:13 (string, required) - Date and time when the payment was created. Format: ISO 8601
    - description: Payment for order (string, optional) - Payment description. No more than 255 characters
    - is_unique: false (boolean, required) - Uniqueness of the order number
    - payment_id: 11639480 (number, required) - Payment identifier
    - payway: card_usd (string, required) - Payment direction. Possible values can be found in your personal account under the shop settings in the Payment Methods section
    - processed (string, required) - Date of payment processing. Format: ISO 8601
    - ps_currency: 840 (number, required) - Currency received in the payment system
    - ps_data (object, required) - Additional information from the payment system, such as payer's account
      - amount (number, optional) - Amount the payer should transfer
      - suggested_amount: 1200 (string, optional) - Only for those using Self-developed Integration and the Bank Transfer payment method. The recommended transfer amount. Advise the payer to transfer this exact amount to speed up payment processing.
      - qr_data (string, optional) - URL that leads to the bank's website for transfer submission form. You need to generate a QR code from this address and display it to the payer on the payment page. Only for the Bank transfer via QR code payment method
      - qr_caption (string, optional) - Recipient's transfer agreement number. Only for the Bank transfer via QR code payment method
      - bank: TINKOFF (string, optional) - Name of the bank to which the payer is making the transfer. Only for the Bank transfer via SBP payment method
      - card (string, optional) - Bank card number to which the payer is making the transfer. Only for bank transfer payment method
      - card_holder_name: Ivanov Ivan Ivanovich (string, optional) - Full name of the individual to whom the payer is making the transfer. Only for bank transfer payment method
      - expired: 1707152043.557505 (string, optional) - Time by which the payer must send the transfer. It is recommended to notify the payer about this. Only for bank transfer payment method
      - phone: 79999999999 (string, optional) - Phone number of the individual to whom the payer is making the transfer. Only for the Bank transfer via SBP payment method
      - currency (string, optional) - Transfer currency. Possible currency values
      - method (string, optional) - Payment method code. Possible values will be provided by your account manager.
      - url (string, optional) - URL address from which to generate a QR code. The value is returned if the method parameter has a qr value. In other cases, an empty value is returned
      - receipt_url (string, optional) - URL address for downloading the receipt via API. Returned if the payment method is bank transfer
      - receipt_status_url (string, optional) - URL address for checking the receipt status via API. Returned if the payment method is bank transfer
      - receipt_web (string, optional) - URL address for downloading the receipt via the form. You need to redirect the payer to this address if you don't want to implement a receipt upload form. Returned if the payment method is bank transfer
    - shop_amount: 10.0 (number, required) - Amount actually paid by the payer
    - shop_currency: 840 (number, required) - Currency in which the payment is credited to the shop
    - shop_id: 3 (number, required) - Your shop's identifier in Feennex
    - shop_order_id: 101 (string, required) - Unique order number in your system. No more than 255 characters
    - shop_original_amount (number, optional) - Initial payment amount. Returned if the payer transferred the wrong amount
    - shop_refund: 9.6 (number, required) - Amount to be credited to your shop's account
    - status: 2 (number, required) - Payment status. More about payment statuses
  - updated (number, required) - Date and time of the last payment status change. Format: ISO 8601. Payment status requests should be made no more frequently than once every 10 seconds. If shop_order_id isn't unique, the response contains "is_unique":false, and the endpoint returns information about the last created payment
  - error_code: 0 (number, required) - Error code. Possible error codes
  - message: Ok (string, required) - Error description. Based on this parameter's value, you can determine the success of the request and find out what went wrong
  - result: true (boolean, required) - Success of the request

Data for HTML form [/h2h_data]

Only for the Self-developed Host-to-Host integration scenario when paying by bank card.

The request returns a token and a URL required to form an HTML form with the payer's card data.

You don't have to generate a signature for this request.

Production URL will be provided by your account manager.

Mandatory request parameter: session_id

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

Click the button below to view the endpoint parameters and request/response bodies.

POST Request data for HTML form [POST]

Request (application/json)
- Attributes
  - session_id: 26d90ef012e34b44aa9d74a3556e15a6 (required, string) - Session identifier you received in response to the Create payment endpoint
- 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) - Token for transmitting card data
  - payform_url: https://example.com/payform (string, required) - URL address to redirect the payer with card data

Send receipts [/api/v1/order/`{id}`/receipt]

Only for the Self-developed Host-to-Host Scenario and those who independently implement the receipt upload page.

Use this endpoint to send the receipt, provided by the payer, to the Feennex support service. You don't need to generate a signature for this request.

You need to obtain the address for sending the request and the value of the id parameter when requesting the payment status

Learn more about sending receipts

Mandatory request parameter: file

Example request

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

Click the button below to view the endpoint parameters and request/response bodies.

POST Send receipt [POST]

Request (application/json)
- Attributes
  - file: /home/cwm/Pictures/receipt.jpg (required, string) - Path to the image of the receipt. Supported formats: JPEG, JPG, PNG, PDF, WebP, HEIF. The image size shouldn't exceed 10 MB.
Response 202 (application/json)
- Body
  
  null

Response 400 (application/json)

Body

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

Request receipt status [/api/v1/order/`{id}`/receipt/status]

Use this endpoint to check the status of the receipt that you sent to the Feennex support service using the Send receipt endpoint. You don't need to generate a signature for this request.

Learn more about sending receipts

Example request

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

Click the button below to view the endpoint parameters and request/response bodies.

GET Request receipt status [GET]

Response 200
- Body
  
  [
```
{
    "id": "c9e35f42-62de-45c4-8092-152ba47d81e5",
    "status": "pending",
    "comment": null
}
```
  ]
- Attributes (object)
  - id (string, required) - Unique identifier of the receipt
  - status: pending (string, required) - Receipt status. Possible values: pending, succeeded, rejected. More about receipt statuses
  - comment: null (string, optional) - Comment on the receipt from Feennex technical support

Response 422

Body

{
    "detail": [
        {
            "loc": [
                "query",
                "order_id"
            ],
            "msg": "value isn't a valid uuid",
            "type": "type_error.uuid"
        }
    ]
}      

Group Payment via third-party payment systems​

Payment precalculation [/invoice/try]​

Precalculate payment [POST]​

Create payment [/invoice/create]​

POST Create payment [POST]​

Request payment status [/invoice/check]​

POST Request payment status [POST]​

Data for HTML form [/h2h_data]​

POST Request data for HTML form [POST]​

Send receipts [/api/v1/order/{id}/receipt]​

POST Send receipt [POST]​

Request receipt status [/api/v1/order/{id}/receipt/status]​

GET Request receipt status [GET]​

Group Payment via third-party payment systems

Payment precalculation [/invoice/try]

Precalculate payment [POST]

Create payment [/invoice/create]

POST Create payment [POST]

Request payment status [/invoice/check]

POST Request payment status [POST]

Data for HTML form [/h2h_data]

POST Request data for HTML form [POST]

Send receipts [/api/v1/order/`{id}`/receipt]

POST Send receipt [POST]

Request receipt status [/api/v1/order/`{id}`/receipt/status]

GET Request receipt status [GET]