IPN (Instant payment notifications) notifications

NOWPayments is a cryptocurrency payment processing platform. Accept payments in a wide range of cryptos and get them instantly converted into a coin of your choice and sent to your Custody balance. Keeping it simple – no excess.

Authentication

To use the NOWPayments API you should do the following:

Sign up at nowpayments.io;
Set up your Primary balance to receive funds;
Generate an IPN secret key;
Please note: IPN secret key may be shown fully only upon creation. Make sure to save it after generation.

NOWPayments Integration Guide

For more detailed information on how to integrate and use the NOWPayments API, please refer to our comprehensive NOWPayments Integration Guide. This guide provides step-by-step instructions on setting up and managing payouts, API requests, and other features to help you get started quickly and effectively.

Integration Scenarios

For a deeper understanding of different integration possibilities, check out our Integration Scenarios Guide. This guide outlines possible integration methods, providing practical examples and insights to help you implement the best solution for your business needs.

Standard e-commerce flow for NOWPayments API:

API – Check API availability with the “GET API status” method. If required, check the list of available payment currencies with the “GET available currencies” method;
UI – Ask a customer to select item/items for purchase to determine the total sum;
UI – Ask a customer to select payment currency;
API – Get the minimum payment amount for the selected currency pair (payment currency to your Primary balance currency) with the “GET Minimum payment amount” method;
API – Get the estimate of the total amount in crypto with “GET Estimated price” and check that it is larger than the minimum payment amount from step 4;
API – Call the “POST Create payment” method to create a payment and get the deposit address (in our example, the generated BTC wallet address is returned from this method);
UI – Ask a customer to send the payment to the generated deposit address (in our example, user has to send BTC coins);
UI – A customer sends coins, NOWPayments processes and exchanges them (if required), and settles the payment to your balance (in our example, to ETH one);
API – You can get the payment status either via our IPN callbacks or manually, using “GET Payment Status” and display it to a customer so that they know when their payment has been processed;
API – you call the list of payments made to your account via the “GET List of payments” method;
Additionally, you can see all of this information in your Account on NOWPayments website;

Alternative flow

API – Check API availability with the “GET API status” method. If required, check the list of available payment currencies with the “GET available currencies” method;
UI – Ask a customer to select item/items for purchase to determine the total sum;
UI – Ask a customer to select payment currency;
API – Get the minimum payment amount for the selected currency pair (payment currency to your Primary balance currency) with the “GET Minimum payment amount” method;
API – Get the estimate of the total amount in crypto with “GET Estimated price” and check that it is larger than the minimum payment amount from step 4;
API – Call the “POST Create Invoice method to create an invoice. Set “success_url” – parameter so that the user will be redirected to your website after successful payment;
UI – display the invoice url or redirect the user to the generated link;
NOWPayments – the customer completes the payment and is redirected back to your website (only if “success_url” parameter is configured correctly!);
API – You can get the payment status either via our IPN callbacks or manually, using “GET Payment Status” and display it to a customer so that they know when their payment has been processed;
API – you call the list of payments made to your account via the “GET List of payments” method;
Additionally, you can see all of this information in your Account on NOWPayments website;

API Documentation

Instant Payments Notifications

IPN (Instant payment notifications, or callbacks) are used to notify you when transaction status is changed.
Please note that no callbacks are sent after a payment expires. Deposits can still be received, but they will not trigger any further IPN callbacks.

To use IPN, you should complete the following steps:

Generate and save the IPN Secret key in Payment Settings tab at the Dashboard;
Insert your URL address where you want to get callbacks in create_payment request. The parameter name is ipn_callback_url. You will receive payment updates (statuses) to this URL address.**
Please, take note that we cannot send callbacks to your localhost unless it has dedicated IP address.**
important Please make sure that firewall software on your server (i.e. Cloudflare) does allow our requests to come through. It may be required to whitelist our IP addresses on your side to get it. The list of these IP addresses can be requested at partners@nowpayments.io;
You will receive all the parameters at the URL address you specified in (2) by POST request;
The POST request will contain the x-nowpayments-sig parameter in the header.
The body of the request is similiar to a get payment status response body.
You can see examples in “Webhook examples” section.
Sort the POST request by keys and convert it to string using
JSON.stringify (params, Object.keys(params).sort()) or the same function;
Sign a string with an IPN-secret key with HMAC and sha-512 key;
Compare the signed string from the previous step with the x-nowpayments-sig , which is stored in the header of the callback request;
If these strings are similar, it is a success.
Otherwise, contact us on support@nowpayments.io to solve the problem.

Example of creating a signed string at Node.JSView More

Plain Text

function sortObject(obj) {
  return Object.keys(obj).sort().reduce(
    (result, key) => {
      result[key] = (obj[key] && typeof obj[key] === 'object') ? sortObject(obj[key]) : obj[key]
      return result
    },
    {}
  )
}
const hmac = crypto.createHmac('sha512', notificationsKey);
hmac.update(JSON.stringify(sortObject(params)));
const signature = hmac.digest('hex');

Example of comparing signed strings in PHPView More

Plain Text

function tksort(&$array)
  {
  ksort($array);
  foreach(array_keys($array) as $k)
    {
    if(gettype($array[$k])=="array")
      {
      tksort($array[$k]);
      }
    }
  }
function check_ipn_request_is_valid()
    {
        $error_msg = "Unknown error";
        $auth_ok = false;
        $request_data = null;
        if (isset($_SERVER['HTTP_X_NOWPAYMENTS_SIG']) && !empty($_SERVER['HTTP_X_NOWPAYMENTS_SIG'])) {
            $recived_hmac = $_SERVER['HTTP_X_NOWPAYMENTS_SIG'];
            $request_json = file_get_contents('php://input');
            $request_data = json_decode($request_json, true);
            tksort($request_data);
            $sorted_request_json = json_encode($request_data, JSON_UNESCAPED_SLASHES);
            if ($request_json !== false && !empty($request_json)) {
                $hmac = hash_hmac("sha512", $sorted_request_json, trim($this->ipn_secret));
                if ($hmac == $recived_hmac) {
                    $auth_ok = true;
                } else {
                    $error_msg = 'HMAC signature does not match';
                }
            } else {
                $error_msg = 'Error reading POST data';
            }
        } else {
            $error_msg = 'No HMAC signature sent.';
        }
    }

Example comparing signed signatures in PythonView More

python

import json 
import hmac 
import hashlib
def np_signature_check(np_secret_key, np_x_signature, message):
    sorted_msg = json.dumps(message, separators=(',', ':'), sort_keys=True)
    digest = hmac.new(
    str(np_secret_key).encode(), 
    f'{sorted_msg}'.encode(),
    hashlib.sha512)
    signature = digest.hexdigest()
    if signature == np_x_signature:
        return
    else:
        print("HMAC signature does not match")

Usually you will get a notification per each step of processing payments, withdrawals, or transfers, related to custodial recurring payments.

The webhook is being sent automatically once the transaction status is changed.

You also can request an additional IPN notification using your NOWPayments dashboard.

Please note that you should set up an endpoint which can receive POST requests from our server.

Before going production we strongly recommend to make a test request to this endpoint to ensure it works properly.

Recurrent payment notifications

If an error is detected, the payment will be flagged and will receive additional recurrent notifications (number of recurrent notifications can be changed in your Payment Settings-> Instant Payment Notifications).

If an error is received again during the payment processing, recurrent notifications will be initiated again.

Example: “Timeout” is set to 1 minute and “Number of recurrent notifications” is set to 3.

Once an error is detected, you will receive 3 notifications at 1 minute intervals.

Webhooks Examples:

Payments:View More

json

{
"payment_id":123456789,
"parent_payment_id":987654321,
"invoice_id":null,
"payment_status":"finished",
"pay_address":"address",
"payin_extra_id":null,
"price_amount":1,
"price_currency":"usd",
"pay_amount":15,
"actually_paid":15,
"actually_paid_at_fiat":0,
"pay_currency":"trx",
"order_id":null,
"order_description":null,
"purchase_id":"123456789",
"outcome_amount":14.8106,
"outcome_currency":"trx",
"payment_extra_ids":null
"fee": {
"currency":"btc",
"depositFee":0.09853637216235617,
"withdrawalFee":0,
"serviceFee":0
}
}

Withdrawals:View More

json

{
"id":"123456789",
"batch_withdrawal_id":"987654321",
"status":"CREATING",
"error":null,
"currency":"usdttrc20",
"amount":"50",
"address":"address",
"fee":null,
"extra_id":null,
"hash":null,
"ipn_callback_url":"callback_url",
"created_at":"2023-07-27T15:29:40.803Z",
"requested_at":null,
"updated_at":null
}

Custodial recurring payments:

json

{
"id":"1234567890",
"status":"FINISHED",
"currency":"trx",
"amount":"12.171365564140688",
"ipn_callback_url":"callback_url",
"created_at":"2023-07-26T14:20:11.531Z",
"updated_at":"2023-07-26T14:20:21.079Z"
}

Repeated Deposits and Wrong-Asset Deposits

This section explains how we handle two specific types of deposits: repeated deposits (re-deposits) and wrong-asset deposits. These deposits may require special processing or manual intervention, and understanding how they work will help you manage your payments more effectively.

Repeated Deposits

Repeated deposits are additional payments sent to the same deposit address that was previously used by a customer to fully or partially pay an invoice. These deposits are processed at the current exchange rate at the time they are received. They are marked with either the “Partially paid” or “Finished” status. If you need to clarify your current repeated deposit settings, please feel free to check it in your personal account -> Settings -> Payments -> Payment details -> Deposits -> Repeated deposits

In the Payments History section of the personal account, these payments are labeled as “Re-deposit”. Additionally, in the payment details, the Original payment ID field will display the ID of the original transaction.

Recommendation: When integrating, we recommend tracking the ‘parent_payment_id’ parameter in Instant Payment Notifications (IPN) and being aware that the total amount of repeated deposits may differ from the expected payment amount. This helps avoid the risk of providing services in cases of underpayment.
We do not recommend configuring your system to automatically provide services or ship goods based on any repeated-deposit status. If you choose to configure it this way, you should be aware of the risk of providing services in cases of underpayment. For additional risk acceptance please refer to section 6 of our Terms of Service.

NB: Repeated deposits are always converted to the same asset as the original payment.

2. Wrong-Asset Deposits

Wrong-asset deposits occur when a payment is sent using the wrong network or asset (e.g. a user may mistakenly send USDTERC20 instead of ETH), and this network and asset are supported by our service.

These payments will appear in the Payments History section with the label “Wrong Asset” and, by default, will require manual intervention to resolve.

Recommendation: When integrating, we recommend configuring your system to check the amount, asset type and the ‘parent_payment_id’ param in Instant Payment Notifications of the incoming deposit to avoid the risks of providing services in case of insufficient funds.

If you want wrong-asset deposits to be processed automatically, you can enable the Wrong-Asset Deposits Auto-Processing option in your account settings (Settings -> Payment -> Payment details -> Deposits). After that, these deposits will be processed automatically at the current exchange rate at the time they are received. They will be marked with either the “Partially paid” or “Finished” status depending on your Default status settings.