Incoming Notifications

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:

Set URLs in your account when creating a shop (recommended).
Provide URLs in the request for creating a payment.

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

Parameter	Description
`client_price`	Amount paid by the payer. Mandatory
`created`	Date and time when the payment was created. Mandatory
`processed`	Date and time when the payment status changed (payment or rejection). Mandatory
`description`	Description of the payment. Mandatory
`payment_id`	Unique identifier of the payment in Feennex. Mandatory
`payway`	Payment direction in Feennex through which the payer makes the payment. Mandatory
`ps_currency`	Currency of the payment direction through which the payer makes the payment. Mandatory
`ps_data`	Additional information from the payment system, for example, the payer's account. Mandatory
`shop_amount`	Payment amount. Mandatory
`shop_currency`	Payment currency. Mandatory
`shop_id`	Unique identifier of your shop. Mandatory
`shop_order_id`	Order identifier on your side. Mandatory
`shop_original_amount`	Payment 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_refund`	Amount credited to the shop's balance
`status`	Payment 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
`sign`	Signature. Mandatory
`Any parameter`	Auxiliary parameters necessary for payment completion