Skip to main content

API Documentation. Complete API documentation for payments, balances, and transactions. Basic URL: https://example.com/

API Feennex (EN)

Feennex is a solution that allows accepting payments online.

With Feennex, your customers can transfer money to you using any of the supported methods. After the payment is made, Feennex verifies its success and transfers the funds to your account.

To start accepting payments, choose the integration scenario, set up a shop, and integrate with Feennex via API.

How to accept payments​

Upon connection, you will set up a Feennex shop. On your account page, you can check the shop's balance and configure parameters for accepting payments.

To initiate the payment process, you need to place the payment form on your website or send a payment request including the payment details to Feennex. You then wait for the request to be processed.

The payer is redirected to the payment page – either yours or a ready-made one. On the payment page, the payer needs to follow the steps below:

  • Choose a payment method

  • Enter payment details

  • If necessary, confirm the payment. For example, undergo 3-D Secure authentication

If the payment is successful, Feennex sends the amount from the payer to your shop's balance. You can withdraw the money through your account or via API.

You can find the available payment methods for your shop in your personal account under Payment methods in the shop settings. To enable additional payment methods, please contact your manager.

About payouts​

With Feennex, you can make payouts from your shop account to Feennex wallets and other external payment systems of your customers.

The available payment systems for your shop can be found in your personal account under Pay ways in the shop settings. To enable additional payout methods, please contact your manager.

Interaction format​

Feennex API comprises several main entities:

  • Payment is used to accept payment from the payer. Payment contains all payment information

  • Payout is used to transfer money from the shop's account to your customers

The payment process depends on the chosen integration scenario.

Basics​

The Feennex API is built on REST principles.

Each API request is associated with a specific action related to payment, or payout, such as creation or status retrieval.

Feennex API uses HTTP making it compatible with any programming language that supports HTTP libraries (for example, Requests, Httpx, Axios, Guzzle).

API endpoint: https://core.feennex.com/<API endpoint>

The API supports POST and GET requests. POST requests use JSON for arguments, while GET requests use string queries. The API always returns a response in JSON format, regardless of the request type.

When sending a request to the Feennex API, you need to specify the header "Content-Type: application/json" and generate a signature using your secret key each time. You can get the secret key in your account.

If you fail to provide mandatory parameters, the response will include an error explaining which parameter is missing from the request.

To work with the Feennex API, you can use ready-made libraries for languages like Python and PHP.

Handle responses​

The Feennex API processes requests immediately and returns the processing result. The response includes the HTTP response code, standard headers, and the response body in JSON format.

Feennex returns the following parameters in the response body:

  • data contains data specific to each request. Type: object
  • error_code contains the error code. Type: number. Example: 0 – no errors. More details on possible error codes
  • result indicates whether the request is successful or not. Type: boolean. Example: true
  • message contains the error description. Type: string. Example: Ok. This parameter's value can help identify what went wrong

Response format​

Response body on success​

The response body is returned in the JSON format. The parameters of the response body depend on the request.

Success response

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

If there's an issue with the request, Feennex returns the response body in JSON format with the error code. More about error codes

Error response for incorrect signature

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

Incoming notifications​

Basics​

Important! Feennex temporarily sends notifications raw data instead of JSON.

Example of a notification in 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"

You can enable notifications (callbacks) for payment-related events. These notifications help you learn when the payment status changes.

For example, it may take Feennex several minutes to process your payment. If your notifications are enabled, you won't have to keep sending requests to get payment information during this time. Wait for the notification from Feennex.

The events on which Feennex sends notifications depend on the type of transaction:

  • Feennex wallet payment
  • Third-party payment method payment

Note: Feennex doesn't send notifications for changes in payout status. You need to request the payout status on your own. Callbacks on input come only for final statuses

Feennex wallet payment​

If you created a payment to receive funds from Feennex wallets (bill), you will receive notifications on the following events:

  • Payment status changed to Paid
  • Payment status changed to Canceled

More about payment statuses

Third-party payment methods​

In case of payments created for third-party payment methods (invoice), you will receive notifications on the following events:

  • Payment status changed to Paid
  • Payment status changed to Recalculated

More about payment statuses

In both cases, Feennex sends notification to the successful payment URL.

Set up notifications​

You need to configure URLs for sending notifications about success and failure.

You can do this in two ways:

The URL must use the HTTPS protocol and TCP port 443.

Note: If you have set URLs in your account and provided them in the request, Feennex sends notifications to the addresses specified in your account. To receive notifications to the addresses provided in the request, remove the notification delivery addresses from your personal account.

Use notifications​

When one of the events occurs, Feennex sends a notification to the URL you provided in the request or specified in the settings of your account.

This notification contains the payment object in its current status. For example, if the payment status changes to success, the notification will return the object of this payment with the status success. Verify the authenticity of the received notification.

Authenticate notifications​

When you receive a notification, authenticate it by verifying the IP address and signature.

Step 1. Verify IP address

Check the IP address from which the notification was sent. Feennex may send notifications from the following IP addresses:

  • 63.177.198.141

Step 2. Verify signature

You need to generate a signature from the parameters received in the notification.

The signature is formed the same way as in the request sending process, but the signature generation includes all parameters whose values aren't an empty string or null.

Example string for signature generation:

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

After you generate the signature, compare it with the signature from the notification. If the signatures match, the notification is authentic.

You can update the payment status in your system to the status received in the notification.

Respond to notification​

You need to confirm that you've received a notification. To do this, respond with HTTP status code 200 and the message body OK.

If you can't confirm that you've received the notification, Feennex resends it for 24 hours with increasing intervals. The last notification will be sent one day after the event.

Notification examples​

Important! Feennex temporarily sends incoming notifications (callback) in raw data instead of JSON.

Notifications on success​

Example of a notification for a successful payment made with a bank card


{ 
    "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",
}

Example of a notification for a successful payment made with Feennex Wallet


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

Notifications on failure​

When Feennex sends a notification about a declined payment, it includes the reason in the rejected_reason parameter.

Example of a notification for a failed payment made with any payment methods besides Feennex wallet

{ 
    "client_price": 1500,
    "created": "2014-12-23 15:26:36",
    "description": null,
    "payment_id": 123166089,
    "payway": "card_usd",
    "processed": "2024-12-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"
}

Notifications Regarding Amount Adjustment (CryptoPay) [note]​

When integrating with the CryptoPay provider, the amount received in the final transaction status (amount) may, in rare cases, differ from the original amount specified during invoice creation.

System Behavior​

  • On receiving a final transaction status (Success, Confirmed, etc.):
    • The amount provided by CryptoPay is compared to the original invoice amount.
    • If the values differ:
      • Qostiq overwrites the amount in its system (overwrite_amount);
      • The updated amount is included in the final callback notification sent to the merchant.

Important for Merchants​

  • Always treat the amount in the callback as the actual credited amount.

Notification parameters​

ParameterDescription
client_priceAmount paid by the payer. Mandatory
createdDate and time when the payment was created. Mandatory
processedDate and time when the payment status changed (payment or rejection). Mandatory
descriptionDescription of the payment. Mandatory
payment_idUnique identifier of the payment in Feennex. Mandatory
paywayPayment direction in Feennex through which the payer makes the payment. Mandatory
ps_currencyCurrency of the payment direction through which the payer makes the payment. Mandatory
ps_dataAdditional information from the payment system, for example, the payer's account. Mandatory
shop_amountPayment amount. Mandatory
shop_currencyPayment currency. Mandatory
shop_idUnique identifier of your shop. Mandatory
shop_order_idOrder identifier on your side. Mandatory
shop_original_amountPayment amount. This parameter appears in the notification if the payer paid the wrong amount. The actual payment amount is contained in the client_price parameter. More details on actions when the payment amount is incorrect
shop_refundAmount credited to the shop's balance
statusPayment status. Mandatory. Possible values:
success – paid and credited.
rejected – rejected by the customer or payment system.
Recalculated – invoice amount has been recalculated. More about statuses
signSignature. Mandatory
Any parameterAuxiliary parameters necessary for payment completion

Get started with API​

Connection flow​

Before integration, you need to complete several steps:

  1. Create a Feennex account and shop

  2. Verify your shop

  3. Get your secret key and configure allowed IP addresses

  4. Set up signature generation in your system

  5. Integrate with Feennex via API

Create Feennex account and shop​

Feennex account​

If you don't have a Feennex account, register and complete the verification process. Now you can proceed to create a shop.

Feennex shop​

Create a new shop. You will send requests to Feennex on behalf of this shop. Specify the name of your shop and its URL. Click Create shop.

After creation, you will see the shop confirmation page.

Shop Confirmation​

Please note! You can complete this step later. To do so, click Skip. You can confirm the shop later in the Shops section of your personal account.

To request activation of your shop and connect payment methods, verify your domain.

In your dashboard under Shops, click on Confirm shop. Download the special file and place it in the root directory of your website on your server or hosting. The file should be accessible for download. Example: http://yourwebsite.com/fnx_0123.txt. Click Confirm.

If everything goes well, your website will be sent for verification. You can contact support for more details.

If the file was added incorrectly, or server/hosting settings prevent the file from being downloaded via the provided link, you will see a notification Unfortunately, we wasn't able to verify your shop. Follow the recommendations in the notification or contact support.

If the verification is successful, the settings page for the created shop will open.

You will see the settings page for the created shop. On this page, you can manage the created shop:

  • Change parameters and settings necessary for payments and payouts
  • View available payment directions and payout ways
  • Manage security settings

Set up Feennex shop​

On the settings page of your created shop, fill in the input fields:

  • Notification URL – the URL where Feennex sends notifications about successful payments

  • Rejected Notification URL – the URL where Feennex sends notifications about rejected payments

  • Success URL – the URL where Feennex redirects the payer after a successful payment

  • Failed URL – the URL where Feennex redirects the payer after a failed payment

Check the box next to Check uniqueness of payments during invoice creation. If checked, the order number on your side (parameter shop_order_id) must be unique for each payment.

Feennex assigns a unique identifier shop_id to your shop. It will be needed for making payouts.

Security settings​

The Security section in your dashboard contains settings for your secret key and a list of allowed IP addresses.

Secret Key​

You can generate a secret key in your dashboard or specify your own.

If you want to use your own secret key, make sure it meets the following criteria:

  • 8 characters long
  • At least one digit
  • Сontains, uppercase and lowercase letters

Don't share your shop's secret key with anyone. This key confirms that operations are made on your behalf.

Allowed IP Addresses​

In the IP Addresses section in the input field, you need to enter the IP address from which you will send requests to Feennex. Then click on the + (plus) button.

If you have multiple IP addresses, you can add them all at once. Use ; (semicolon) as a separator.

Generate signature​

For each request, you need to generate a signature using your secret key and send it in the sign parameter.

The secret key is responsible for the security of your data. Keep it in a secure place and don't publish it on third-party resources. You can obtain the secret key in your dashboard in the shop settings.

How to generate a signature​

Step 1. Sort all the required parameters alphabetically, convert them to string data type, and concatenate them into one string. Use : (colon) as a delimiter. Append your secret key to the end of the string without the : sign.

Note: Some parameters require special attention:

  • The mandatory parameter email shouldn't be included in the string

  • When generating a signature for the amount parameter, send one decimal place for whole amounts or if the fractional part is a multiple of 10, for example 12.0. For other amounts, use two decimal places, for example 12.01

Example of combining parameters into one string for a request to create a payment:

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

Replace the curly braces with the values of the parameters being passed. The number of parameters in your request may vary.

Example of the resulting string

12.34:840:bank_usd:5:4126SecretKey01

Step 2. Calculate the SHA256 hash of the concatenated string.

Example HEX representation of the signature

6e99ea937bea47c8a996b6462e04304925c82f205bad21bf44917d36fe016923

You can use an online service for online verification.

Example of generating a signature in Python:

# Required request parameters for generating a signature

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

# Additional request parameters. They aren't involved in generating the signature

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

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

Step 3. Send the obtained value in the request in the sign parameter.

Example of generating a signature for the Create payment endpoint

{
  "currency": "840",
  "sign": "c438896efecd63",
  "payway": "bank_usd",
  "amount": "12.34",
  "shop_id": "5",
  "shop_order_id": 4126,
  "description": "Payment for order #123"
}

Integration with Feennex via API​

After completing the previous steps, you can proceed with the integration. It depends on the integration scenario you want to use.

Choose integration scenario​

You can integrate using one of three scenarios:

Choose the appropriate scenario and inform Feennex manager about your decision.

Feennex payment page scenario​

Fundamentals​

The payment form contains a set of fields with the order and payment details. In your shop, you need to place the form on the page that the payer sees after placing an order.

When the payer clicks the confirm button, the payment details are sent to Feennex.

Submitting the form starts the payment process on Feennex's side. The payer is then redirected to the Feennex payment page.

On the payment page, payers can select a payment method, enter their information if needed, and complete the payment.

Features​

If the payment currency doesn't match your shop's payment direction, the payment page will convert the amount. Your shop will receive the payment in currency of the payment direction, and the payer will pay in their chosen currency.

If a new payment method is connected to your shop, it will be immediately available on the payment page.

Generating HTML form​

To redirect the payer to the Feennex payment page, you need to generate an HTML form.

HTML form example​

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="Payment for order #123" 
/form

Payment form parameters​

URL address for form submission​

Submit the form to https://pay.feennex.com/en/pay. Please note that the payment page supports multiple languages.

Form parameters​
ParameterFormatDescription
Required Parameters
shop_idIntegerYour shop's identifier in the Feennex system. Example: 5
amountNumberPayment amount. Up to two digits after the decimal point. Example: 1.00
currencyNumberPayment currency. Example: 840 Possible currency values
descriptionStringPayment description. Example: Payment for order #123. No more than 255 characters
shop_order_idStringOrder number on your side. Example: h8fj38. Feennex may check the uniqueness of the order number depending on shop settings. No more than 255 characters
signStringRequest signature. Use only required parameters to generate signature
Optional Parameters
paywayStringPayment direction through which the payment is made. Example: card_usd
payer_accountStringEmail or wallet number of the payer's account in Feennex. Example: [email protected] or 201494711279. If you send this parameter, only this account can make the payment. Only for payments from Feennex Wallet
failed_urlStringURL where Feennex will redirect the payer after a failed payment. Example: https://feennex.com/failed
success_urlStringURL where Feennex will redirect the payer after successful payment. Example: https://feennex.com/success

Payment creation scenario (Redirect scenario)​

In this scenario, you choose the payment method on your side, and the payer enters the payment data on the Feennex side. You can accept payments through the Feennex wallet or third-party payment methods.

You need to implement the payment method selection yourself and notify the payer of the payment results.

The API endpoints you use depend on the chosen payment method.

Example of implementation:

  1. The payer on your side proceeds to payment (for example, clicks a button).
  2. You create a payment, receive the URL of the payment page in response, and redirect the payer to the URL.
  3. The payer on the payment page enters bank card and wallet data or sees details for the transfer.
  4. The payer makes the payment.
  5. Feennex redirects the payer back to the completion page on your side.

Payment process for Feennex Wallet payment

Payment process for card payment

Important! Make sure that you have completed all the preparatory steps before starting the integration.

For API integration, you need to create a payment, obtain a link to the payment page, and redirect the payer to this page.

Payment via Feennex Wallet​

Note: For payment via Feennex Wallet, use endpoints for receiving payments with Feennex Wallets. Such methods have the prefix bill in the URL.

Step 1. Create a payment. In the request, send the amount, currency, payment direction, your shop ID, and order ID. Send the signature in the sign parameter.

Example request:

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

You can include URLs for your success and failure pages in the request to redirect the payer after payment, along with a URL where Feennex will send notifications.

Before transmitting the URLs, make sure that you have removed old addresses from your account settings that were specified when creating the shop – these addresses have higher priority. More details about shop configuration

Step 2. Redirect the payer to the url returned in the response in the data object. This is a link to the Feennex payment page, where the payer will enter Feennex Wallet details and confirm the payment.

Example response

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

If the payment is successful, Feennex performs the following actions:

  • Changes the payment status to Paid
  • Redirects the payer to the success page you provided in the request or specified in your shop settings in the dashboard
  • Sends a callback about the success to the URL you provided in the request or specified in your shop settings in the dashboard

If something goes wrong, Feennex performs the following actions:

  • Changes the payment status to Expired or Canceled
  • Redirects the payer to the failure page you provided in the request or specified in your shop settings in the dashboard
  • Sends a notification about the failure to the URL you provided in the request or specified in your shop settings in the dashboard

Additionally, you can check the payment status when paying with a wallet.

Payments via other methods​

Note: For payments made with any methods besides the Feennex wallet, you need to use the Create payment endpoint. Send the request to a URL with the invoice prefix.

Step 1. Create a payment. In the request, include the amount, currency, payment direction, your shop's identifier, and order identifier. Send the request signature in the sign parameter.

Example request

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

In the request, you can additionally send URLs for your success and failure pages to redirect the payer after payment, as well as the URL to which Feennex will send notifications.

Before transmitting the URLs, ensure that you have removed any old addresses from your account settings specified when creating the shop, as these addresses have higher priority. More details about shop setup

Step 2. Redirect the payer to the url returned in the response in the data object. This link leads to a external payment system where the payer will enter their details and confirm the payment.

Example response

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

If the payment is successful, Feennex performs the following actions:

  • Changes the payment status to success
  • Redirects the payer to the success page you provided in the request or specified in the settings of your shop in your dashboard
  • Sends a notification about the success to the URL you provided in the request or specified in your dashboard

If something goes wrong, Feennex performs the following actions:

  • Changes the payment status to Rejected or another status indicating an error
  • Redirects the payer to the failure page you provided in the request or specified in the settings of your shop in your dashboard
  • Sends a notification about the failure to the URL you provided in the request or specified in your dashboard

Additionally, you can check the payment status when paying by bank card.

Self-developed integration (Host-to-Host scenario)​

In this scenario, you handle both the selection of payment method and inputting payment data on your side.

You can accept payments via bank transfer or with credit/debit cards. Card payments require PCI DSS compliance certification. If you don't have the certificate, choose another integration scenario.

You need to implement the following steps independently:

  • Let the payer select the payment method
  • Collect payment data from the payer for the selected method
  • Inform the payer about the payment results

The integration process varies depending on the chosen payment method.

Payment by bank card​

Note: To accept bank card payments, you must have a certificate compliant with the requirements of PCI DSS. If you don't have a certificate, choose another integration scenario.

To integrate via API, you need to follow these 4 steps:

  1. Create a payment and obtain a session identifier

  2. Get a token and a URL address

  3. Create an HTML form

  4. Redirect the payer to the HTML form

Step 1. Create payment​

To create a payment, use the Create payment endpoint, but in the payway parameter, send the value for the Host-to-Host scenario. You can obtain this value from your manager or check it in the settings of your shop in the personal account. Typically, payway parameter has the prefix h2h. Example: bank_h2h_usd.

Example request for creating a payment

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
       }

In the response, Feennex returns the session ID in the session_id parameter. Save this identifier: you will need it in the following steps.

Example response


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

Step 2. Obtain token and URL address​

To obtain a token, use the Data for HTML Form endpoint. In the request body, send the session identifier you received in the previous step in the session_id parameter.

Example request for obtaining the token

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

In the response, Feennex returns the form_token and payform_url parameters. Save them: you will need them for the next step.

Example response

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

Step 3. Make payment form​

You need to collect the payer's bank card information and send a request to create an HTML form.

Collect payer's bank card details​

Note: You must have a certificate compliant with the PCI DSS requirements.

On your side, you need to implement a page for entering the payer's bank card details. On this page, you will need to collect the following data:

  • Card validity date (year and month)
  • Three-digit CVV or CVC code
  • Card number
  • Name and surname of the cardholder
Send request to create HTML form​

You need to send a POST request to create an HTML form. Send the request to the payform_url you received in the previous step. In the request body, include the payer's bank card details, form_token, and the session_id session identifier.

Example request to create the payment form:

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

In the response, Feennex returns an HTML form.

Step 4. Redirect payer to HTML form​

Redirect the payer to the HTML form you received in the response on the previous step. The payer will be automatically directed to the 3D-secure page where they will be asked to enter the code.

If the payment is successful, Feennex will redirect the payer to the Success URL. If the payment fails or the code is incorrect, Feennex will redirect the payer to the Failed URL.

Payment via bank transfer​

Payers will be able to transfer payment to a bank account using one of the following methods:

  • QR code — the payer sees a QR code, scans it, and follows the deep link to either the browser or the mobile banking app, if installed, to complete the transfer.

  • Card number — the payer sees the card number to which the transfer should be sent.

To integrate via API, you need to follow three steps:

  • Create a payment

  • Obtain transfer details

  • Request payment status

The interaction occurs asynchronously: after successfully creating the payment, you can immediately attempt to obtain transfer details.

Step 1. Create a payment​

To create a payment, use the Create payment endpoint, but in the payway parameter, pass the value for the Host-to-Host scenario. You can get this value from your manager or check it in the settings of your shop in the personal account. Typically, it has the prefix h2h. For example, sbp_h2h_usd.

Example request for creating a payment 
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
       }'
Response example 
{
   "data":{
      "data":{},
      "id":123456789,
      "method":"sbp",
      "url":"bank"
   },
   "error_code":0,
   "message":"Ok",
   "result":true
}

Step 2. Obtain transfer details​

After creating a payment, you need to obtain the transfer details. You must display this information to the payer on your payment page.

To obtain transfer details, use the Request payment status for other payment methods endpoint.

Note: If transfer details are not available, repeat the request later — transfer details are not assigned to the payment immediately.

Example request for obtaining transfer details

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 returns a standard response. The ps_data object contains the transfer details.

Note! In some cases Feennex can return a suggested amount in the suggested_amount parameter. Recommend that the payer transfers this suggested amount and inform them that this will decrease the time needed to process the payment.

Example of a message with a suggested transfer amount

You requested a payment of X but there are currently no bank requisites for that amount.

We recommend you to pay XX to procced with this transaction.

Example response

{
   "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,
         "suggested_amount": "1200",
         "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": 2,
      "updated": "2024-02-05 18:37:18"
   },
   "error_code": 0,
   "message": "Ok",
   "result": true
}

The ps_data object consists of the following parameters:

ParameterTypeDescription
amountnumberAmount that the payer should pay
suggested_amountstringSuggested transfer amount. Recommend the payer to transfer this amount to decrease payment processing time.
bankstringName of the recipient bank. Returned if the method parameter has a value of sbp. Otherwise, it returns an empty value
cardstringRecipient's bank card number. Returned if the method parameter has a value of bank. Otherwise, it returns an empty value
card_holder_namestringName of the cardholder
currencystringCurrency of the transfer
expiredstringTime by which the payer should send the transfer. It is recommended to notify the payer about this
methodstringPayment method code. The possible values will be provided by your manager.
phonestringPayer's phone number. Returned if the method parameter has a value of sbp. Otherwise, it returns an empty value
urlstringURL address to generate the QR code from. Returned if the method parameter has a value of qr. Otherwise, it returns an empty value

Step 3. Request payment status​

After displaying the payment details, you can check the payment status: either periodically send a request or wait for a successful callback.

If you're sending a request, use the Request payment status for third-party payment systems endpoint.

In the Host-to-Host scenario, the statuses work the same way as when creating a payment request.

If the status parameter in the response returns the value 4, it means the payer has successfully made the payment and the funds have been credited to your shop. More about payment statuses

Example of a successful response

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

After payment​

Refunds​

Refunds in Feennex depend on the payment method. Detailed information will be provided by your manager.

Incorrect payment amount​

Note: The payer can specify an incorrect amount only when using the bank transfer payment method.

If the payer transfers an incorrect amount, the payment status changes to recalculated. This status is final and unchangeable. Feennex sends you a notification about the payment status change to recalculated.

In the received notification and when requesting payment status, the actual amount transferred by the payer is returned in the client_price parameter. The initial payment amount is returned in the shop_original_amount parameter.

Your actions vary based on whether or not the payer has transferred enough money for the payment.

Insufficient payment​

Create a new order for the missing amount. If it doesn't meet the minimum limit, accept payment from the payer using another method.

Overpayment​

You need to arrange with the payer how you will compensate for the overpaid amount.

Payer made payment via bank transfer, but status remains unchanged​

Note: Only for bank transfer payment method.

If the payer has made a payment via bank transfer but the payment status remains unchanged, they should have the option to send a receipt with information about the transfer.

You can implement a page for uploading the receipt and send the receipt to Feennex via API, or use a ready-made form for sending the receipt.

Step 1. Implement receipt upload page​

Note: If you don't want to implement your own receipt upload page, proceed to step 2.

On the receipt upload page, it is recommended to inform the payer that the size of the image cannot exceed 10 MB, and the receipt should clearly display the following information:

  • Transfer time
  • Sender and recipient of the transfer
  • Transfer amount

Example page for uploading receipts

Note: For each payment, the payer can only submit one receipt. Supported formats: JPEG, JPG, PNG, PDF, WebP, HEIF.

Step 2. Request payment status​

To work with receipts, you need to obtain the value of the id parameter, which is unique for each payment. To get this value, request the payment status. The response returns the following parameters in the ps_data object:

  • receipt_url – URL for uploading a receipt via API
  • receipt_status_url – URL for checking the status of a receipt via API
  • receipt_web – URL for uploading a receipt via a form. You should redirect the payer to this address if you don't want to implement the receipt upload form yourself

Example of the receipt_url parameter

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

In this parameter, https://<baseURL>/api/v1/order/ is the URL for sending requests to upload a receipt. The ade32e06-6fa4-425a-9c4c-e026ac6d93e6 string is the value of the id parameter.

Step 3. Send receipt to Feennex​

Only for those who have implemented the receipt upload page (step 1).

Use the Send receipts endpoint to send a receipt that payers uploaded to Feennex. You don't need to generate signature for this endpoint.

The address to send the request to and the value of the id parameter are obtained at step 2 in the receipt_url parameter.

Example request

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

If you successfully send the receipt, the response will have an HTTP status code of 202.

Example successful response

null

Once you send the request, Feennex's technical support processes the transfer.

To make sure that the transfer is successful, periodically send requests to request payment status.

Step 4. Display receipt status information​

Note: This step is optional.

Request receipt verification status and display it on your payment page. To do this, use the Check receipt status endpoint. No signature is required for this endpoint.

To request the receipt status, you need the address to send the request and the value of the id parameter. You obtained these values in step 2 in the receipt_status_url parameter.

Example request

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

In the response, you receive the receipt identifier, receipt status, and a comment from Feennex's technical support.

Example of a successful response

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

Once the status changes to succeed, it means that the receipt has been accepted. Make sure that the payment is completed: periodically request payment status.

Failed payment​

In the payment process, issues may occur, such as payment creation failures or bank unavailability. Feennex provides a payment object with the status parameter to help understand what happened with the payment.

Use the status to determine the payment's state and use this data for analysis, communicating with the payer, or other purposes.

Learn more about statuses for failed transfers

Registers​

Feennex generates registers for successful transactions, useful for reconciling accounts. These registers include the following types of operations:

  • Accepted payments
  • Completed payouts
  • Service operations

Feennex collects information on all transactions for the day — from 00:00:00 to 23:59:59 UTC+3.

You can request reports for one day, one week, or one month.

In your personal account, within the History section, you have the option to independently generate registers for specific shops. Alternatively, if you wish to receive registers periodically via email, you can subscribe to this service.

Subscription to register distribution​

To receive notifications from Feennex by email, provide the following information to your manager:

  • Email addresses of recipients
  • Names of the shops for which registers need to be sent
  • Period for which the register should be generated – day, week, or month

The format of the register file is XSL. If there were no operations for the specified date, Feennex will send you an empty register.

Fields in the register​

Field in the registerDescription
Creation dateDate of the operation
Operation IDUnique identifier of the payment, payout, or service operation
Shop IDIdentifier of your shop in Feennex
Credited to the shopActual amount credited to your shop, taking into account commissions. Only for payments
Debited from the shopActual amount debited from your shop for payouts or service operations. Includes Feennex commission
CurrencyCurrency of the payment – the value of the currency parameter from the payment creation request for wallet payment or shop_currency from the payment creation request for third-party payment methods.

Possible currency values
Operation typeType of the operation being performed. Possible values: Payments, Payouts, Service
Invoice amountPayment amount – the value of the amount parameter from the payment creation request for wallet payment or shop_amount from the payment creation request for other payment methods
Invoice currencyCurrency of the payment direction. Possible currency values
Payer amountPayment or payout amount, including commission. Only for payouts. Possible currency values
Payer currencyCurrency of the direction for payout. Only for payouts. Possible currency values
Order numberOrder number on your side
DescriptionOperation description – the value of the description parameter from the payment creation request for wallet payment and other payment methods
BalanceCurrent balance of your shop after the operation is performed
Project IDService parameter. The parameter isn't used
FeeCommission amount for payment or payout

Example of a register​

"Creation date" "Operation ID" "Shop ID" "Invoice amount" "Debited from the shop" "Currency" "Operation type" "Invoice amount" "Invoice currency" "Payer amount" 
"Payer currency" "Order number" "Description" "Balance" "Project ID" "Fee"
2024-04-19 17:07:43 50000000 1234 282,94 840 Payments 301 840 i171e2d956-d3b4-457d-a26a-52d960 i171e2d956-d3b4-457d-a26a-52d960 9393,74 18,06

Payouts​

A payout is an operation to transfer money from your shop's balance to Feennex Wallets or third-party payment systems.

For example, you've received a payment from a payer into your shop account and want to withdraw this money to a bank card.

How payouts work​

If you've already accepted payments using Feennex, you already have one or more shops. Each shop has a balance - the money that payer have transferred to you.

Before making a payout:

  • Check the balance of your shop in your personal account
  • Get payout details from your customer, such as the Feennex Wallet number or the bank card number to transfer the money to
  • Make sure you comply with payout limits, depending on the customer's chosen method of receiving money. Your manager will provide you with applicable limits

Ask your manager to find out the commission amount for your specific case.

Payout methods​

Using the Feennex API, you can make payouts to Feennex Wallets and third-party payment systems. In the personal account, you can find the list of supported payment systems in the settings of your shop under the Pay Ways section. To enable additional payment systems, contact your account manager.

Payouts to Feennex Wallets​

Payout process to Feennex Wallets​

  • Step 1. Optional step. Request a preliminary payout calculation: send a Feennex POST request with data on the amount to be debited from your shop's balance and to which wallet to transfer it
  • Step 2. Create a payout: send a Feennex POST request with data on the amount to be debited from your shop's balance and to which wallet to transfer it

Feennex processes the payout to the provided wallet and returns the payout identifier. This means the payout is successful.

Perform payout via API

Step 1. Request a payout precalculation. In the request, send the payout amount, currency, type of the transmitted payout amount, currency of the payout, currency of the shop's debit, and your shop's identifier. In the sign parameter, send the request signature.

Request example

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

Response example

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

Step 2. Create a payout to a wallet. In the request, provide the payout amount, recipient's account for the payout in Feennex, type of the transmitted payout amount, currency of the payout receipt, currency of the shop's debit, your shop's identifier, and a unique payout identifier on your side. In the sign parameter, provide the request signature.

Request example

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

Response example

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

The payout is successful!

If an error occurred in the response, you can request the payout status to Feennex Wallet.

Payouts to external payment systems​

  • Step 1. Request a payout precalculation: send a Feennex POST request with data on the amount to be debited from your shop's balance and to which payment system to transfer it. Additional parameters may be returned in the account_info_config parameter, which must be passed in subsequent requests.
  • Step 2. Check the possibility of making a payout to the selected payment system from the Feennex side: send a Feennex POST request.
  • Step 3. Create a payout: send a Feennex POST request with data on the amount to be debited from your shop's balance and to which payment system to transfer it. Feennex processes the payout to the selected payment system and returns you the payout object with the current status.
  • Step 4. Periodically check the payout status, no more than once per minute. If the status is 5 (Success), the payout is successful, and the money is debited from your shop's balance.

Perform payout via API

Step 1. Request a payout precalculation. In the request, send the payout amount and currency, type of the transmitted payout amount, direction for the payout, and your shop's identifier. In the sign parameter, provide the request signature.

Request example

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

Response example

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

If the response includes additional parameters in the account_info_config object, except for account, you should send these parameters in the Create payout request within the account_details parameter.

Step 2. Check the possibility of making a payout.

In the request, include the recipient's account for payout verification, payout direction, payout amount, your shop's identifier, and any additional account information if available. Use the sign parameter to provide the request signature.

Request example

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

Response example

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

Step 3. Create a payout to the account.

In the request, include the payout amount, recipient's account for the payout, type of transmitted amount, currency of the shop's debit, your shop's identifier, and a unique payout identifier on your side. Use the sign parameter to provide the request signature.

Request example for creating a payout

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

Response example

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

Step 4. Request the payout status using the payout identifier or the payout number in your system. In the request, provide the request sending time, your shop's identifier, and the payout identifier. In the sign parameter, provide the request signature.

Request example for getting the payout status by the payout identifier

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

Example of a successful payout object


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

The parameter status has the value 5, indicating success. More about statuses for payouts to external accounts

The payout is successful!

Group Payment via Feennex Wallet​

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

Create payment when paying with Wallet [/bill/create]​

Use this endpoint to create a payment to accept payments from Feennex Wallets.

If you want to accept the payment through other methods, create a payment using the endpoint Create payment.

To use this method, you need to generate a signature using the required request parameters: payer_currency, shop_amount, shop_currency, 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.

Request example

curl https://core.feennex.com/bill/create \
   -H 'Content-Type: application/json' \
   -d '{
          "description": "Payment for order #123", 
          "payer_currency": 840, 
          "shop_amount": "23.15", 
          "shop_currency": 840, 
          "shop_id": "3", 
          "shop_order_id": 4239, 
          "sign": "ad7fbe8df102b" 
       }'

Example of an error response

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

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

POST Create payment when paying with wallet [POST]​

  • Request (application/json)

    • Attributes

      • payer_currency: 840 (number, required) - Currency of the payer's payment. This currency may differ from the shop's currency. Possible currency values
      • shop_amount: 23.15 (string, required) - Payment amount
      • shop_currency: 840 (number, required) - Currency in which the payment is credited to your shop. Possible currency values
      • shop_id: 3 (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
      • description: Payment for order (string, optional) - Payment description. No more than 255 characters
      • payer_account: 1a2b3c (string, optional) - Payer's Feennex account making the payment
      • lifetime: 43200 (number, optional) - Payment lifetime in minutes. When the payment expires, its status changes to Expired. If the payment isn't passed, the lifetime will be 43200 minutes
      • failed_url: https://feennex.com/failed (string, optional) - URL to which the payer is redirected after an failed payment. If you want to pass a URL in the request, remove the value from the corresponding address in 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 a URL in the request, remove the value from the corresponding address in shop settings in the dashboard
      • callback_url (string, optional) - URL to which a notification of successful payment is sent. If you want to pass a URL in the request, remove the value from the corresponding address in shop settings in the dashboard
      • callback_rejected_url (string, optional) - URL to which a notification of rejected payment is sent. If you want to pass a URL in the request, remove the value from the corresponding address in shop settings in the dashboard

    • Body

      { 
          "description": "Payment for order #123", 
          "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": 643,
              "payer_price": 500,
              "shop_amount": 500,
              "shop_currency": 643,
              "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) - Object contains payment data
        • created: Wed, 10 Apr 2024 14:18:19 GMT (string, required) - Date of payment creation. Format: RFC 5322
        • id: 26 (number, required) - Unique identifier of the payment in Feennex
        • lifetime: 43200 (number, required) - Payment lifetime in minutes. When the payment expires, its status will be changed to Expired. Default value - 43200 minutes
        • payer_account: 1a2b3c (string, optional) - Feennex account of the payer who is making the payment. Returned if you passed this parameter in the request
        • payer_currency: 840 (number, required) - Currency in which the payer makes the payment. This currency may differ from the shop's currency. Possible currency values
        • payer_price: 23.15 (number, required) - Amount the payer must pay. Includes Feennex commission
        • shop_amount: 10.0 (number, required) - Payment amount
        • shop_currency: 840 (number, required) - Currency in which the payment is credited to your shop. Possible currency values
        • shop_id: 3 (number, required) - Identifier of your shop in Feennex
        • shop_order_id: 101 (string, required) - Unique order identifier in your system. No more than 255 characters
        • url: https://wallet.feennex.com/en/bill/pay/Waptm (string, required) - URL to which you need to redirect the payer
      • error_code: 0 (number, required) - Error code. Possible error codes
      • message: Ok (string, required) - Error description. Based on the value of this parameter, 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 when paying with Wallet [/bill/shop_order_status]​

Use this endpoint to check the current status of a payment for which the payer made a payment using Feennex Wallet. More about payment statuses when paying with a Wallet

Important! Request the status no more often than once every 10 seconds.

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.

Request example

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

Example response in case of an error

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

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

POST Request payment status when paying with Wallet [POST]​

  • Request (application/json)

    • Attributes

      • now (string, required) - Date and time when you send the request. Format: ISO 8601
      • shop_id: 1092 (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-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) - Object contains payment data
        • client_price: 1.16 (number, required) - Amount actually transferred by the payer
        • created: 2024-10-20 14:01:28 (string, required) - Date and time of payment creation. Format – ISO 8601
        • is_unique (boolean, required) - Uniqueness of the order number on your shop's side. If you have already created a payment with this order number, false is returned. In this case, the endpoint returns information about the last payment made with a wallet payment.
        • payment_id: 852095 (number, required) - Payment identifier on the Feennex side
        • payway: feennex_rub (string, required) - Payment direction
        • 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 ps_payer_account: 201538122124 (string, required) - Payer's account in Feennex
        • shop_amount: 10.0 (number, required) - Payment amount
        • 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_refund: 1.1 (number, required) - Amount credited to the shop's balance, in the account currency
        • status: 2 (number, required) - Payment status. More about statuses
        • description: Main account (string, optional) - Payment description. No more than 255 characters
      • 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

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 Payout to Feennex Wallet​

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

Precalculate payout to Feennex Wallet [/transfer/try]​

This endpoint is optional for creating a payout to Feennex Wallet. It returns additional information for creating a payout to the wallet with a preliminary calculation of the commission.

To use this method, you need to generate a signature using the required request parameters: amount, amount_type, payee_currency, shop_currency, and shop_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/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"
       }'

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

POST Precalculate payout [POST]​

  • Request (application/json)

    • Attributes

      • amount: 1 (number, required) - Amount to receive or debit, depending on the amount_type parameter
      • amount_type: receive_amount (string, required) - Parameter determines the type of amount. receive_amount - the amount of the payout that will be credited to the wallet, writeoff_amount - the amount that will be debited from your shop's balance
      • payee_currency: 840 (string, required) - Currency in which the payout will be credited to Feennex Wallet. Possible currency values
      • shop_currency: 840 (number, required) - Currency from which the payout will be debited from your shop's account. Possible currency values
      • shop_id: 1 (number, required) - Your shop's identifier from which the payout is made
      • sign: cea33ec0eeeef98 (string, required) - Request signature

    • 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) - Information about the payout
        • account_info_config (object, required) - Information about an account to which the payout will be made
          • payee_account (object, required) - Additional information about the account to which the payout will be made. Parameters in the object may vary for each payout direction
        • info (object, required) - Service parameter
        • payee_amount: 1.11 (number, required) - Amount that will be credited to your account
        • payee_currency: 978 (number, required) - Currency of the amount that will be credited to your account
        • shop_currency: 840 (number, required) - Currency of the amount that will be debited from your shop's account
        • write_off_amount (number, required) - Amount that will be debited from the shop's account
      • error_code: 0 (number, required) - Error code. Possible error codes
      • message: Ok (string, required) - Error description. Based on the value of this parameter, you can determine the success of the request and find out what went wrong
      • result: true (boolean, required) - Success of the request

Create payout to Feennex Wallet [/transfer/create]​

Use this endpoint tp create a payout to transfer money from your shop balance to Feennex Wallet.

Important! Once a payout is created, no status is returned the response. If a payout is created to the wallet and the payout ID (id parameter) is returned in the response, then the payment is considered successful.

To use this method, you need to generate a signature using the required request parameters: amount, amount_type, payee_account, payee_currency, shop_currency, shop_id, and shop_payment_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/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"
       }'

More about payouts to Feennex Wallet

The endpoint isn't mandatory for creating a payout to the wallet. It returns additional information for creating a payout to the wallet with a preliminary commission calculation.

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

Create payout to Feennex Wallet [POST]​

  • Request (application/json)

    • Headers

    • Attributes

      • amount: 1 (number, required) - Amount to receive or debit, depending on the amount_type parameter
      • amount_type: receive_amount (string, required) - Defines the type of amount. Possible values: receive_amount - the amount that will be received to your account including all commissions. writeoff_amount - the amount that will be debited from the shop balance. Doesn't include commissions
      • payee_account: 201497141132 (string, required) - Account of the recipient of money in Feennex. Wallet number or email
      • payee_currency: 840 (string, required) - Currency in which the payout will be received by the Feennex account. Possible currency values
      • shop_currency: 840 (number, required) - Currency in which the payout will be debited from your shop. Possible currency values
      • shop_id: 1 (number, required) - Identifier of your shop from which the payout will be debited
      • shop_payment_id (string, required) - Number of the payout on your side. Must be unique for each new payment
      • sign: cd30ba2b6e29f5 (string, required) - Request signature

    • 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) - Payment data
        • balance: 88.91 (number, required) - Balance of your shop after payment
        • id (number, required) - Unique payment identifier
        • payee_account: 201497141132 (number, required) - Payee account in Feennex system. You can pass your wallet number or email
        • payee_currency: 840 (number, required) - Currency in which the payment will be received on the wallet
        • shop: 112 (number, required) - ID of Feennex shop
        • shop_currency (number, required) - Currency in which the payment will be debited from your shop's account
        • write_off_amount (number, required) - The amount that will be debited from your shop's account
      • error_code: 0 (number, required) - Error code. Possible error codes
      • message: Ok (string, required) - Error description. By the value of this parameter you can determine the success of the request and find out what went wrong
      • result: true (boolean, required) - Success of the request

Request status of payout to wallet [/transfer/shop_payment_status]​

If you received an error in the response when creating payout to Wallet, request the status of the payout. The endpoint returns the status of the payout to Feennex Wallet by the order number on your side:

  • If the response returns id and transfer details, the payout has been created and successfully completed.
  • If an error is returned that the payout wasn't found, you need to recreate payout to Wallet.

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.

Example request

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": "2018-01-23 16:45:14.145107", 
          "sign": "e76c5ed9431d"
       }'

Response example if a payment is created and successfully made

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

Example of an error response

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

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

Request status of payout to wallet [POST]​

  • Headers

  • Content-Type: application/json

  • Request (application/json)

    • Attributes

      • now (string, required) - The date and time when you send the request. Format: ISO 8601
      • shop_id: 1 (number, required) - The identifier of your store from which the payout is made
      • shop_payment_id (string, required) - The payout identifier on your side. Must be unique for each new payout.
      • sign: cd30ba2b6e29f5 (string, required) - The request signature

    • Body

      { 
          "shop_id": 112, 
          "shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561322", 
          "now": "2024-01-23 16:45:14.145107", 
          "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) - Payment data
        • id (number, required) - Payment identifier
        • payee_currency: 840 (number, required) - Currency of the payout that will be credited to your wallet
        • receive_amount: 1 (number, required) - Amount that will be credited to your wallet
        • shop_currency: 840 (number, required) - Currency in which the payment will be debited from your shop account
        • shop_payment_id (string, required) - Unique identifier of the payment on the side of your shop
        • write_off_amount (number, required) - Amount of debit from the shop. The currency of this amount corresponds to the value of the shop_currency parameter
      • error_code: 0 (number, required) - Error code. Possible values of error codes
      • message: Ok (string, required) - Error description. By the value of this parameter you can determine the success of the request and find out what went wrong
      • result: true (boolean, required) - Success of the request

Group Payout to external payment systems​

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

Precalculate payout [/withdraw/try]​

The endpoint is optional. Returns additional information to create a payout with a pre-calculated fee.

To use this method, you need to generate a signature using the required request parameters: shop_currency, amount_type, payway, amount, and shop_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/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 
       }'

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

Precalculate payout [POST]​

  • Request (application/json)

    • Headers

    • Attributes

      • shop_currency: 840 (number, required) - Currency of debiting your shop's account. Possible currency values
      • amount_type: receive_amount (string, required) - Parameter specifies the type of amount. Possible values: ps_amount - the amount that will be transferred to the recipient's account in the payment system, shop_amount - the amount that will be debited from your shop's balance
      • sign: 32b2c32caa8ad (string, required) - Request signature
      • payway: card_usd (string, required) - Direction for payout. Possible values you can find out in your personal account in the settings of your shop in the Pay Ways section. The currency of receipt depends on the transferred direction for payment
      • amount: 1 (number, required) - Receipt or debit amount. Depends on the value of the amount_type parameter
      • shop_id: 1 (number, required) - Identifier of your shop, from which the payment is made

    • 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) - Payment data
        • account_info_config (object, required) - Information about an account to which the payment will be made.
          • account (object, required) - Additional information about an account to which the payment will be made. The parameters in the object may be different for each payout direction
          • regex: \\d{9,15}$ (string, required) - Regular expression that the account must match
          • title: 79123456789 (string, required) - Name of the account field
        • payee_receive: 1 (number, required) - Amount of the payment that will be credited to the recipient’s account in the external system
        • ps_currency: 840 (number, required) - Currency of the payment direction
        • shop_currency (number, required) - Currency in which the payment will be debited from the shop account
        • write_off_amount (number, required) - Amount to be debited from the shop in the wallet currency
      • error_code: 0 (number, required) - Error code. Possible error codes
      • message: Ok (string, required) - Error description. By the value of this parameter you can determine the success of the request and find out what went wrong
      • result: true (boolean, required) - Success of the request

Check account [/check_account]​

The endpoint returns information about whether payouts can be made to a specific account. The endpoint isn't required to create a payout, but it's recommended.

*To use this method, you need to generate a signature using the required request parameters: account, payway, amount, and shop_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.

The response to the payout precalculation request may return the account_info_config object with additional parameters. You need to send these parameters, except for account, in the Create payout request within the account_details parameter.

Example request

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

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

Check account [POST]​

  • Request (application/json)

    • Headers

    • Attributes

      • account: 4111111111111111 (string, required) - Main account to be checked for the possibility of replenishment. The format for each payout direction may differ: you can check the information in your personal account
      • account_details (object, optional) - Additional information for account verification
        • contract: C1234 (string, optional) - Contract number of the account to be checked for the possibility of replenishment.
      • sign: 32b2c32caa8ad (string, required) - Request signature
      • payway: card_usd (string, required) - Direction for payout. Possible values you can find out in your personal account in the shop settings in the Pay Ways section. The currency of receipt depends on the transferred direction for payout
      • amount: 1 (number, required) - Amount of planned crediting to the account in the currency of the payment direction. It is necessary to check replenishment limits
      • shop_id: 1 (number, required) - Identifier of your shop from which the payment is made

    • 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) - Verification data
        • account_info (object, required) - Additional information returned from the service provider, can be displayed to the payer, as it often contains his personal information, for example, the name of the account owner
          • verified: true (boolean, required) -
        • provider_status: 1 (number, required) - Provider's response status to the request to verify the possibility of account replenishment, format: 1 - provider is available, the verification has passed without errors; 2 - error on the provider, the result of the verification is unknown; 3 - error in processing the request, the result of the verification is unknown
        • result: true (boolean, required) - Result of checking if the account can be recharged
      • error_code: 0 (number, required) - Error code. Possible values of error codes
      • message: Ok (string, required) - Error description. By the value of this parameter you can determine the success of the request and find out what went wrong
      • result: true (boolean, required) - Success of the request

Create payout [/withdraw/create]​

Use this endpoint to create a payout to transfer funds from your Feennex shop balance to available payment systems, other than Feennex Wallet.

To use this method, you need to generate a signature using the required request parameters: account, amount, amount_type, payway, shop_currency, shop_id, and shop_payment_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.

The shop_payment_id parameter must be unique for each request.

You can find the reason for the payout rejection in the rejected_reason parameter, which is returned in the Create payout and Request payout status endpoints.

Request example

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

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

POST Create payout [POST]​

  • Request (application/json)

    • Headers

    • Attributes

      • account: 4111111111111111 (string, required) - Payee's account in the payment system, for example, card number
      • amount: 1 (number, required) - Receipt or debit amount. Depends on the value of the amount_type parameter
      • amount_type: ps_amount (string, required) - Parameter defines the type of amount. Possible values: ps_amount - amount to be received in the payment system, shop_amount - amount to be debited from the balance of your shop
      • email: [email protected] (string, required) - Payee's email. Exclude this parameter from signature generation
      • payway: card_usd (string, required) - Direction for payout. Possible values you can find out in your personal account in the settings of your shop in the Pay Ways section. The currency of receipt depends on the transferred direction for payment
      • shop_currency: 840 (number, required) - Currency in which the payment will be debited from your shop account. Possible currency values
      • shop_id: 1 (number, required) - Identifier of your shop from which the payment will be debited
      • shop_payment_id (string, required) - Unique identifier of the payout on your side
      • sign: 32b2c32caa8ad (string, required) - Request signature
      • account_details (object, optional) - Object with additional information about the payee's account. The composition of parameters in the object depends on the selected direction for payouts. The list of parameters can be viewed in the personal account for each direction
      • description: Payout (string, optional) - Description of payout. The value is passed in the payment destination, if the payment system has this function. No more than 255 characters

    • 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) - Payment data
        • balance: 0.0 (number, required) - Balance of your shop after successful creation of the payment
        • id: 11298076 (number, required) - Unique identifier of the payment on the Feennex side
        • payee_receive: 1 (number, required) - Amount of the payment that will be credited to the recipient’s account in the external system
        • shop_currency: 840 (number, required) - Currency in which the payment will be debited from your shop account
        • shop_payment_id (string, required) - Unique identifier of the payment on your side
        • shop_write_off: 1.02 (number, required) - Amount that will be deducted from your shop account
        • status: 3 (number, required) - Payment status
      • error_code: 0 (number, required) - Error code. Possible error codes
      • message: Ok (string, required) - Error description. By the value of this parameter you can determine the success of the request and find out what went wrong
      • result: true (boolean, required) - Success of the request

Request payout status by payout ID [/withdraw/status]​

Use this endpoint to get the status of a payout by payout identifier - withdraw_id parameter.

Request the payment status not more often than once a minute.

To use this method, you need to generate a signature using the required request parameters: now, shop_id, and withdraw_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/withdraw/status \
   -H 'Content-Type: application/json' \
   -d '{
          "now": "2024-01-23 16:56:25.009469",
          "shop_id": 112,
          "withdraw_id": 11298076,
          "sign": "e1dfc97b2c5430"
       }'

Example response in case of an error

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

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

POST Request payout status [POST]​

  • Request (application/json)

    • Headers

    • Attributes

      • now (string, required) - Date and time when you send the request. Format: ISO 8601
      • shop_id: 1 (number, required) - Identifier of your shop from which the payment is made
      • withdraw_id: 112 (number, required) - Unique identifier of the Feennex payment for which you want to know the status.
      • sign: 32b2c32caa8ad (string, required) - Request signature

    • Body

      {
          "now": "2024-01-23 16:56:25.009469",
          "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) - Payment data
        • id: 11298076 (number, required) - Unique identifier of the payment on the Feennex side
        • payee_receive: 1 (number, required) - Amount of the payment that will be credited to the recipient’s account in the external system
        • ps_currency: 840 (number, required) - Currency of payment receipt in the payment system
        • rejected_reason: Card number doesn't exist. Check if the number is correct (string, optional) - Reason for canceled payment
        • shop_currency: 840 (number, required) - Currency in which the payment will be debited from your shop account
        • shop_payment_id (string, required) - Unique identifier of the payment on your side
        • shop_write_off: 1.02 (number, required) - Amount of debit from your shop
        • status: 5 (number, required) - Payout status. Possible status values
      • error_code: 0 (number, required) - Error code. Possible values of error codes
      • message: Ok (string, required) - Error description. By the value of this parameter you can determine the success of the request and find out what went wrong
      • result: true (boolean, required) - Success of the request

Request payout status by payout number in your system [/withdraw/shop_payment_status]​

Use this endpoint to get the status of a payment by the number of the payout in your system - the shop_payment_id parameter.

It's recommended to request the payment status not more often than once a minute.

To use this method, you need to generate a signature using the required request parameters: now, shop_id, and shop_payment_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/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"
       }'

Example response in case of an error

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

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

POST Request payout status by payout number in your system [POST]​

  • Request (application/json)

    • Headers

    • Attributes

      • shop_id: 1 (number, required) - Identifier of your shop, from which the payment is made
      • shop_payment_id (string, required) - Unique number of the payout on your side
      • now (string, required) - Date and time when you send the request. Format: ISO 8601
      • sign: 32b2c32caa8ad (string, required) - Request signature

    • Body

      {
           "shop_id":112,
           "shop_payment_id": "63288d86-241c-418e-94b8-db4bbf5026f",
           "now": "2011-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) - Payment data
        • id: 11298076 (number, required) - Unique identifier of the payment on the Feennex side.
        • payee_receive: 1 (number, required) - Amount of the payment that will be credited to the payee’s account in the external system
        • ps_currency: 840 (number, required) - Currency of payment in the payment system
        • shop_currency: 840 (number, required) - Currency in which the payment will be debited from your shop account.
        • shop_payment_id (string, required) - Unique number of the payment on your side
        • shop_write_off: 1.02 (number, required) - Amount of debit from your shop account
        • status: 5 (number, required) - Current status of the payout. Possible status values
      • error_code: 0 (number, required) - Error code. Possible values of error codes
      • message: Ok (string, required) - Error description. By the value of this parameter you can determine the success of the request and find out what went wrong.
      • result: true (boolean, required) - Success of the request

Group Interaction with the shop​

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

Request shop balance [/shop_balance]​

Use this endpoint to check the balance of your Feennex shop.

To use this method, you need to generate a signature using the required request parameters: now and shop_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.

The shop balance consists of the following values:

  • available – The amount available for payouts, excluding the rolling_reserve
  • frozen – A frozen amount on the balance. For example, for a payout that is being processed
  • hold – A temporarily held amount. For example, during the verification of an incoming payment

Request example

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

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

Request shop balance [POST]​

  • Request (application/json)

    • Headers

    • Attributes

      • shop_id: 1 (number, required) - Identifier of your shop, from which the payment is made
      • shop_payment_id (string, optional) - Identifier of the transaction on the shop side
      • now (string, required) - Date and time when you send the request. Format: ISO 8601
      • sign: 32b2c32caa8ad (string, required) - Request signature

    • 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": 643,
                      "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) - Balance information
        • balances (array, required) - shop balance by currencies
          • object
            • available: 93.0 (number, required) - Available balance of the shop
            • currency: 840 (number, required) - Balance currency. Possible currency values
            • hold: 0.0 (number, required) - Temporarily withheld funds, for example, when checking an incoming receipt.
            • frozen: 20.0 (number, required) - Frozen funds in the shop’s balance
            • rolling_reserve 0.0 (number, optional) - Temporarily held funds in the shop’s balance
        • shop_id: 112 (number, required) - Identifier of your Feennex shop
      • error_code: 0 (number, required) - Error code. Possible error codes
      • message: Ok (string, required) - Error description. By the value of this parameter you can determine the success of the request and find out what went wrong.
      • result: true (boolean, required) - Success of the request

Request available payment directions [/shop_input_config/shop]​

The endpoint returns available payment directions for your shop. For example, payment by bank card or Feennex Wallet.

To use this method, you need to generate a signature using the required request parameters: now and shop_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/shop_input_config/shop \
   -H 'Content-Type: application/json' \
   -d '{
          "shop_id":112,
          "now": "2024-04-12T06:18:34.719Z",
          "sign": "77c6cc948751ee"
       }'

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

POST Request available payment directions [POST]​

  • Request (application/json)

    • Headers

    • Attributes

      • now (string, required) - Date and time when you send the request. Format: ISO 8601
      • shop_id: 112 (number, required) - Identifier of the shop from which the payment is made
      • sign: 32b2c32caa8ad (string, required) - Signature of the request

    • 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_rub",
                          "currency": 643,
                          "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) - Available payment directions data
        • object
          • id: 3 (number, required) - Payment method identifier
          • is_bill_config (boolean, optional) - Parameter that indicates that the direction is intended for payments
          • name: MIR (string, required) - Name of payment method
          • payways (array, required) - Payment directions that are enabled for the shop
            • object
              • add_ons_config (string, optional) - Additional information, if required for the payment direction
              • alias: card_usd (string, required) - Name of payment direction
              • currency: 840 (number, required) - Currency by payment direction. Possible currency values
              • fee_config (object) - Settings of commission distribution between the shop and the payer.
                • fix: 0.0 (number, required) - Fixed fee
                • percent: 6.0 (number, required) - Percentage commission distribution (0,0-1,0)
              • fee_part_config (object, optional) - ???? settings of commission distribution between shop and payer
                • fix: 0.0 (number, required) - fixed commission????
                • percent: 6.0 (number, required) - ????percentage commission????
              • id: 154 (number, required) - Id of payment direction
              • is_active: true (boolean, required) - Activation status
              • max_amount: 100000.0 (number, required) - Maximum amount of payment by direction
              • min_amount: 1.0 (number, required) - Minimum payment amount by direction
          • rating (number, optional) - Service parameter
      • error_code: 0 (number, required) - Error code. Possible values of error codes
      • message: Ok (string, required) - Error description. By the value of this parameter you can determine the success of the request and find out what went wrong.
      • result: true (boolean, required) - Success of the request

Request available payout directions [/shop_output_config/shop]​

The endpoint returns the available payment destinations for your shop. For example, payment to a bank card.

To use this method, you need to generate a signature using the required request parameters: now and shop_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/shop_output_config/shop \
   -H 'Content-Type: application/json' \
   -d '{
          "shop_id":3,
          "now": "03.09.2024 11:19:55",
          "sign": "588485c9d7f0d"
       }'

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

POST Request available payout directions [POST]​

  • Request (application/json)

    • Headers

    • Attributes

      • now (string, required) - Date and time when you send the request. Format: ISO 8601
      • shop_id: 1 (number, required) - Identifier of your shop, from which the payment is made
      • sign: 32b2c32caa8ad (string, required) - Signature of the request

    • 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) - Data on available payment destinations
        • id: 3 (number, required) - Payment method identifier
        • is_transfer_config (boolean, optional) - Parameter that indicates that the direction is intended for payments.
        • name: MIR (string, required) - Name of payment method
        • payways (array, required) - Directions for payments that are connected for your shop
          • object
            • account_info_config (object) - Information about an account to which the payout will be made
              • account (object) - Additional account information
                • regex (string, required) - Regular expression to which the account must match
                • title (string, required) - Name of the account field
          • alias: card_rub (string, required) - Name of payment direction
          • currency: 643 (number, required) - Currency by payment direction. Possible currency values
          • fee_config (object) - Fee amount
            • fix: 0.0 (number, required) - fixed fee
            • percent: 6.0 (number, required) - percentage fee
          • info_id: null (string, required) - Service parameter
          • max_amount: 10000.0 (number, required) - Maximum payment amount by direction
          • min_amount: 0.5 (number, required) - Minimum payment amount by direction
        • rating: 22 (number, required) - Service parameter
      • error_code: 0 (number, required) - Error code. Possible error codes
      • message: Ok (string, required) - Error description. By the value of this parameter you can determine the success of the request and find out what went wrong.
      • result: true (boolean, required) - Success of the request

Request Feennex service availability [/check_status]​

Use this endpoint to check the availability of Feennex service.

Example request

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

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

GET Request Feennex service availability [GET]​

  • Headers

  • Content-Type: application/json

  • Request

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

  • Response 200 ()

    • Body

      {
          "status": "OK"
      }

    • Attributes (object)

      • status: OK (string, required) - Status of service availability

Group Error codes​

The error code is returned in the response in the error_code parameter.

Example response in case of an error

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

Possible error codes

Error codeDescriptionExample error message
1PaywayNotFound: The payment method is disabled: the Status option is turned off in the payment method settings.
2PaywayNotUsed: Payment direction is not in use
3PaywayNotAvailable: Payment direction is not availablePayway (alias = card_usd) is not available for shop
4AmountTooSmall: Amount is too small
5AmountTooLarge: The amount is too large
6OperationNotUnique: The operation with the provided ID already exists in the system
7OperationNotFound: Operation not foundWithdraw (id=1234567) wasn't found
8OperationIsProcessing:The processing field value for the operation is set to true. This happens when an external system requests operation status while querying the provider.
9InsufficientBalance: Insufficient balance to execute the operationInsufficient balance(currency=840): shop_write_off=500.0, balance=0.0
10IncorrectRequestParam: Invalid request parameterInvalid sign, string_to_sign: 500:840:bank_h2h_usd:6199:99991
11ShopNotFound: shop not found
12ShopNotActive: Shop inactive
13AccountNotFound: The account with the provided ID was not found in the Feennex database.
14IncorrectAccountStatus: Incorrect account status
15RequestIpDenied: Request IP address deniedShop ip 111.111.111.111.111 denied
16InvalidCurrencyExchange: Failed to convert the amount: there is no exchange rate information, or the exchange rate is invalid, for example, 0
17InvalidShopContract: The shop does not have a contract to perform the specified type of operation
18IncorrectAccountType: This account type (personal or business) cannot perform the specified operation
19ShopAggregatorRequire: shop aggregator required!
20InvalidProject: Deprecated
21ProjectNotActive: Deprecated
27DailyLimitExceeds. Daily payout limit has been exceeded
33WeekLimitExceeds: Weekly payout limit exceeded
34MonthLimitExceeds: Monthly payout limit exceeded
41The amount does not match the regular expression set for the payment direction"en": "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"
100IncorrectOperationStatus: The operation cannot be processed with the current status
2000Other error that does not fit into other categoriesService error

Group Possible statuses​

If a payment or payout is successfully created, Feennex will return a unique identifier and the status of the transaction in the response. Payments and payouts have different statuses.

The status can be final and non-final. Continue to request a status until one of the final statuses is returned.

Payment statuses differ depending on which payment method you created the payment for:

Payment statuses for payments with Feennex Wallet​

StatusValueDescription
1WaitingPayment is awaiting payer action
2PaidPayment has been successfully paid by the client. Final status
3CanceledPayment has been canceled by the client. Final status
4ExpiredPayment has expired. Final status

Payment statuses for external payment methods​

StatusValueDescription
1CreatedPayment has been created and is awaiting processing
2WaitingPayment is awaiting payer action
3PsCreatingErrorError occurred during payment creation on the payment system side
4SuccessPayment has been successfully processed. Final status
5CallbackErrorDeprecated. The parameter isn't used for new payments
6PsRejectedPayment has been rejected by the payment system. Final status
7RefundedPayment amount has been refunded to the payer by the payment system. Final status
8HoldA callback with a failed payment status has been received from the payment system, except for Recalculated
9PtxRefundedPayment amount has been refunded to the payer by the Feennex system. Final status
10CapturedPayment amount has been captured by the payment system
11RefundingPayment amount is in the process of being refunded: a refund request has been sent to the payment system.
12RecalculatedPayment amount has been recalculated. Final status. The payer sent a different amount when paying instead of the one specified when creating the payment. More about actions when the payment amount is incorrect

Payout statuses​

Payout statuses vary depending on where you are transferring the money.

Payout statuses for Feennex Wallet​

There is no status for payouts to the wallet. If the response includes the id parameter (unique payout identifier), it means the payout is successful. You don't need to request the payout status additionally.

Payout statuses for external account transfers​

If the payout is successfully created, the response includes a unique payout identifier and its status.

The status can be final or non-final. Keep requesting the payment status until you receive one of the final statuses.

StatusValueDescription
1CreatedPayout has been created and is awaiting processing
2WaitingManualConfirmationPayout requires manual confirmation from the operator
3PsProcessingPayout has been sent to the payment system
4PsProcessingErrorError occurred during payout on the payment system side. Try requesting the status later or contact support
5SuccessPayout has been completed. Funds have been deducted from your shop's account. Final status
6RejectedPayout has been rejected by the payment system. Funds haven't been deducted from the shop's account. Final status
7ManualConfirmedPayout has been confirmed by the operator and is awaiting processing
9PsNetworkErrorNetwork error on the payment system side
10CanceledManuallyPayout has been manually canceled on the Feennex system. Final status
11RefundedPayout has been successfully canceled manually by Feennex. Final status

Receipt statuses​

Note: Receipts are only relevant for bank transfers, when the payer has made the payment but the payment status hasn't changed.

A receipt that you have submitted to technical support using the Send receipts endpoint can have one of the following statuses:

StatusDescription
pendingReceipt has been received and is being verified
succeedReceipt has been successfully verified. This status doesn't indicate that the transfer has been completed
rejectedReceipt verification has failed

Periodically send requests to Request receipt status to check the status of a receipt.

Group Available currencies​

The table lists the main currencies supported by Feennex. For each currency, the code follows the ISO-4217 standard. A full list of supported currencies can be provided by your account manager.

CodeCurrency name
398Kazakhstani tenge
417Kyrgyz Som
643Russian ruble
860Uzbek soum
840US dollar
944Azerbaijani manat
978Euro
949
Turkish lira
980UAH

Group Terms​

TermDescription
Bank transferAn external payment method where the payer deposits funds into the bank account specified on the payment page
FeennexFeennex is an electronic payment solution that allows you to accept payments and make payouts
MerchantParticipant who accepts payments
PayerParticipant who makes the payment
PaymentOne of the core entities in the Feennex API. Payment is necessary for making transactions. It contains a status that indicates the current state of the payment. More about payment statuses
Payment directionThe route that a payment takes. Each direction has its own limits and supported currencies
PayoutOne of the core entities in the Feennex API. Payout is used to withdraw money from the shop's account to your account
Payment pagePage on which the payer makes the payment. If you are using Self-developed integration, you need to implement this page on your own

Group Feennex logos​

Feennex Logo

Feennex Medium Logo

Feennex Small Logo

All versions of the logo are available in the logo repository.

Group API Change history​

DateEvent
27.02.2025Changes for the payment method Transfer to bank account. Now Feennex can offer the payer to transfer the suggested amount. Transferring the suggested amount will speed up the fund deposit. If you are using Self-developed Integration, you need to update your system. For other integration scenarios, no action is required.
16.01.2025Feennex temporarily sends incoming notifications (callback) in raw data instead of JSON
10.12.2024A new error reason 41 has been added. It is returned if the transaction amount does not match the regular expression. This expression is configured in the admin panel under Платежные системы > Управление ПН
27.11.2024We've updated the list of IP addresses from which Feennex may send notifications.
02.10.2024Launch of the new documentation

Group Contacts​

If you have any questions, please contact your manager or email [email protected]