NOWPayments API

OpenAPI apis-guru financial

NOWPayments is a non-custodial 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 wallet. Keeping it simple – no excess.

Sandbox

Before production usage, you can test our API using the Sandbox. Details can be found

Authentication

To use the NOWPayments API you should do the following:

Sign up at
Specify your outcome wallet
Generate an API key

Standard e-commerce flow for NOWPayments API:

API - Check API availability with the method. If required, check the list of available payment currencies with the 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 Outcome Wallet currency) with the method;
API - Get the estimate of the total amount in crypto with and check that it is larger than the minimum payment amount from step 4;
API - Call the 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 Outcome Wallet (in our example, to your ETH address);
API - You can get the payment status either via our IPN callbacks or manually, using 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 method. Additionally, you can see all of this information in your on NOWPayments website.

Alternative flow

API - Check API availability with the method. If required, check the list of available payment currencies with the 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 Outcome Wallet currency) with the method;
API - Get the estimate of the total amount in crypto with and check that it is larger than the minimum payment amount from step 4;
API - Call the 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 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 method. Additionally, you can see all of this information in your on NOWPayments website.

API Documentation

Instant Payments Notifications

IPN (Instant payment notifications, or callbacks) are used to notify you when transaction status is changed.
To use them, you should complete the following steps:

Generate and save the IPN Secret key in Store 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.
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 response body.
Example:
{"payment_id":5077125051,"payment_status":"waiting","pay_address":"0xd1cDE08A07cD25adEbEd35c3867a59228C09B606","price_amount":170,"price_currency":"usd","pay_amount":155.38559757,"actually_paid":0,"pay_currency":"mana","order_id":"2","order_description":"Apple Macbook Pro 2019 x 1","purchase_id":"6084744717","created_at":"2021-04-12T14:22:54.942Z","updated_at":"2021-04-12T14:23:06.244Z","outcome_amount":1131.7812095,"outcome_currency":"trx"}
Sort all the parameters from the POST request in alphabetical order.
Convert them to string using
(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 to solve the problem.

Example of creating a signed string at Node.JS

Example of comparing signed strings in PHP

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);            ksort($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.';        }    }

Recurrent payment notifications

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

If an error is received again during processing of the payment, 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.

Several payments for one order

If you want to create several payments for one Order you should do the following:

Create a payment for the full order amount.
Save "purchase_id" which will be in "create_payment" response
Create next payment or payments with this "purchase_id" in "create_payment" request.
Only works for partially_paid payments

It may be useful if you want to give your customers opportunity to pay a full order with several payments, for example, one part in BTC and one part in ETH. Also, if your customer accidentally paid you only part of a full amount, you can automatically ask them to make another payment.

Packages

Please find our out-of-the box packages for easy integration below:

[PHP package]
()

More coming soon!

Payments

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);            ksort($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.';        }    }

Homepage: https://api.apis.guru/v2/specs/nowpayments.io/1.0.0.json
Provider: nowpayments.io
OpenAPI version: 3.0.3
Spec (JSON): https://api.apis.guru/v2/specs/nowpayments.io/1.0.0/openapi.json
Spec (YAML): https://api.apis.guru/v2/specs/nowpayments.io/1.0.0/openapi.yaml

Tools (18)

Extracted live via the executor SDK.

billingSubPartnerApi.getAllTransfers

Returns the entire list of transfers created by your sub-partners.
billingSubPartnerApi.getSubPartnerBalance

This request can be made only from a whitelisted IP.
If IP whitelisting is disabled, this request can be made by any user that has an API key.
billingSubPartnerApi.getSubPartners

This method returns the entire list of your sub-partners.
billingSubPartnerApi.getTransfer

Get the actual information about the transfer. You need to provide the transfer ID in the request.
paymentsApi.getEstimatedPrice

This is a method for calculating the approximate price in cryptocurrency for a given value in Fiat currency. You will need to provide the initial cost in the Fiat currency (amount, currency_from) and the necessary cryptocurrency (currency_to) Currently following fiat currencies are available: usd, eur, nzd, brl, gbp.
paymentsApi.getListOfPayments
Returns the entire list of all transactions, created with certain API key. The list of optional parameters:
- limit - number of records in one page. (possible values: from 1 to 500)
- page - the page number you want to get (possible values: from 0 to page count - 1)
- sortBy - sort the received list by a paramenter. Set to created_at by default (possible values: payment_id, payment_status, pay_address, price_amount, price_currency, pay_amount, actually_paid, pay_currency, order_id, order_description, purchase_id, outcome_amount, outcome_currency)
- orderBy - display the list in ascending or descending order. Set to asc by default (possible values: asc, desc)
- dateFrom - select the displayed period start date (date format: YYYY-MM-DD or yy-MM-ddTHH:mm:ss.SSSZ).
- dateTo - select the displayed period end date (date format: YYYY-MM-DD or yy-MM-ddTHH:mm:ss.SSSZ).
paymentsApi.getPaymentStatus
Get the actual information about the payment. You need to provide the ID of the payment in the request.
NOTE! You should make the get payment status request with the same API key that you used in the create payment request. Here is the list of avalable statuses:
- waiting - waiting for the customer to send the payment. The initial status of each payment.
- confirming - the transaction is being processed on the blockchain. Appears when NOWPayments detect the funds from the user on the blockchain.
- confirmed - the process is confirmed by the blockchain. Customer’s funds have accumulated enough confirmations.
- sending - the funds are being sent to your personal wallet. We are in the process of sending the funds to you.
- partially_paid - it shows that the customer sent the less than the actual price. Appears when the funds have arrived in your wallet.
- finished - the funds have reached your personal address and the payment is finished.
- failed - the payment wasn't completed due to the error of some kind.
- refunded - the funds were refunded back to the user.
- expired - the user didn't send the funds to the specified address in the 24 hour time window.
Additional info:
- outcome_amount - this parameter shows the amount that will be (or is already) received on your Outcome Wallet once the transaction is settled.
- outcome_currency - this parameter shows the currency in which the transaction will be settled.
- invoice_id - this parameter shows invoice ID from which the payment was created
paymentsApi.getTheMinimumPaymentAmount

Get the minimum payment amount for a specific pair.
You can provide both currencies in the pair or just currency_from, and we will calculate the minimum payment amount for currency_from and currency which you have specified as the outcome in the Store Settings.
You can also specify one of the fiat currencies in the currency_from. In this case, the minimum payment will be calculated in this fiat currency.
You can also add field fiat_equivalent (optional field) to get the fiat equivalent of the minimum amount.
In the case of several outcome wallets we will calculate the minimum amount in the same way we route your payment to a specific wallet.
paymentsApi.getUpdatePaymentEstimate

This endpoint is required to get the current estimate on the payment, and update the current estimate.
Please note! Calling this estimate before expiration_estimate_date will return the current estimate, it won’t be updated.
:id - payment ID, for which you want to get the estimate
Response:
id - payment ID
token_id - id of api key used to create this payment (please discard this parameter)
pay_amount - payment estimate, the exact amount the user will have to send to complete the payment
expiration_estimate_date - expiration date of this estimate
payoutsApi.verifyPayout
This method is required to verify payouts by using your 2fa code.
You’ll have 10 attempts to verify the payout. If it is not verified after 10 attempts, the payout will remain in ‘creating’ status.
Payout will be processed only when it is verified.
Make sure to have your 2fa authentication enabled in your NOWPayments Account (in Account Settings).
When 2fa is disabled, the code automatically goes to your registration email.
The code sent by email is valid for one hour.
Next is a description of the required request fields:
- :batch-withdrawal-id - payout id you received in 2. Create payout method
- verification_code - 2fa code you received with your Google Auth app or via email
In order to establish an automatic verification of payouts, you should switch 2FA through the application.
There are several libraries for different frameworks aimed on generating a 2FA codes based on a secret key from your account settings.
e.g: Speakeasy for JavaScript.
We do not recommend to change any default settings.
const 2faVerificationCode = speakeasy.totp({ your_2fa_secret_key, encoding: 'base32',})
recurringPaymentsApiEmailSubscriptionsFeature.deleteRecurringPayment

Completely removes a particular payment from the recurring payment plan.
You need to specify the payment plan id in the request.
recurringPaymentsApiEmailSubscriptionsFeature.getManyPlans

This method allows you to obtain information about all the payment plans you’ve created.
recurringPaymentsApiEmailSubscriptionsFeature.getManyRecurringPayments

The method allows you to view the entire list of recurring payments filtered by payment status and/or payment plan id
recurringPaymentsApiEmailSubscriptionsFeature.getOnePlan

This method allows you to obtain information about your payment plan.
(you need to specify your payment plan id in the request).
recurringPaymentsApiEmailSubscriptionsFeature.getOneRecurringPayment

Get information about a particular recurring payment via its ID.
Here’s the list of available statuses:
- WAITING_PAY
- PAID
- PARTIALLY_PAID
- EXPIRED
recurringPaymentsApiEmailSubscriptionsFeature.updatePlan

This method allows you to add necessary changes to a created plan. They won’t affect users who have already paid; however, the changes will take effect when a new payment is to be made.
openapi.previewSpec

Preview an OpenAPI document before adding it as a source
openapi.addSource

Add an OpenAPI source and register its operations as tools