NOWPayments API Create Payment Invoice Webhook Ipn Documentation: Complete Guide

Integrating a cryptocurrency payment gateway into an application requires understanding how payments are created, tracked, and confirmed through the system. The NOWPayments ecosystem provides a straightforward REST API for generating payment invoices, managing transactions, and receiving real-time notifications when payments are completed. This guide covers the complete flow from creating an invoice to handling incoming webhook events. For developers looking to implement this functionality, the api create payment invoice webhook ipn documentation outlines the available endpoints and authentication methods.

Getting Started with the API

Before creating any payment invoices, you need an account and API credentials. The platform offers both testnet and mainnet environments, allowing developers to verify their integration without moving real funds. Testnet mode uses the same API endpoints but routes payments through a simulated network where transactions complete instantly.

To begin, generate an access key from the account dashboard. Store this key securely — it authenticates every API request. All requests require the x-api-key header set to your access key value. The base URL for production is https://api.nowpayments.io/v1, while testnet uses https://testnet-api.nowpayments.io/v1.

API calls follow standard HTTP conventions. Most operations use POST for resource creation and GET for retrieval. Responses return JSON payloads containing status codes, data objects, and error messages when applicable. Rate limits apply depending on your plan tier, so implement basic retry logic with exponential backoff for failed requests.

When building the integration, focus on the core workflow: create an invoice, display it to the customer, listen for webhook notifications, and update your order state accordingly. Each step has specific requirements that ensure smooth transaction processing.

Creating a Payment Invoice

The primary endpoint for initiating a crypto payment is the create invoice endpoint under the orders namespace. This endpoint accepts parameters that define the payment amount, currency pair, and optional metadata.

POST /v1/order
{
  "price_amount": 49.99,
  "price_currency": "usd",
  "pay_currency": "btc",
  "ipn_callback_url": "https://yoursite.com/webhook/nowpayments",
  "order_id": "ORD-2026-00847",
  "order_description": "Premium subscription renewal",
  "buy_crypto": false,
  "is_fixed": true
}

The response returns an order object with a unique order_id assigned by NOWPayments, along with the payment instructions including the address to send funds to, the exact amount to transfer, and a QR code for mobile wallets. The pay_amount field may differ slightly from the original price_amount due to real-time exchange rate adjustments between the time of invoice creation and payment submission.

Invoice Parameters Explained

Several parameters control the behavior of the payment page. Setting is_fixed to true locks the exchange rate at creation time, preventing the required amount from changing if the market moves before the customer pays. The buy_crypto flag enables an embedded exchange widget for users who want to purchase the target cryptocurrency directly from a debit card. The ipn_callback_url parameter specifies where webhook notifications should be sent — this is critical for automating order fulfillment.

If you prefer using the payments endpoint instead of orders, the flow is nearly identical but operates at a lower level. The /v1/payment endpoint creates a direct payment instruction rather than a full order record. Use payments when you manage your own order tracking system and only need NOWPayments as a payment processor. Orders provide built-in status management which simplifies integrations significantly.

Configuring Webhook Notifications

Webhooks, known internally as IPN (Instant Payment Notification), are the mechanism that keeps your system synchronized with payment status changes. When a customer completes a payment, NOWPayments sends a POST request to your callback URL with the updated transaction details. Without a properly configured webhook, your application would need to poll the API repeatedly, adding latency and unnecessary API calls.

Set the ipn_callback_url either during invoice creation per-request, or configure a default callback URL in your account settings that applies to all orders. Per-request configuration takes precedence over the default setting. The callback URL must be publicly accessible and respond with a 200 OK status code within ten seconds. If your server does not acknowledge receipt, NOWPayments retries the delivery up to five times with increasing intervals.

Each webhook payload contains the following fields:

The purchase_status field transitions through several states: waiting, confirming, confirmed, sending, sent, and finished. Your webhook handler should treat finished and sent as successful completion indicators. The confirming state means the blockchain network has detected the transaction but required confirmations are still pending. Do not fulfill orders at this stage.

Webhook Retry Behavior

Understanding the retry schedule helps design robust handlers. The first retry attempts approximately two minutes after the initial failure. Subsequent retries occur at progressively longer intervals — roughly five, fifteen, thirty, and sixty minutes. After five failed delivery attempts, the webhook event is marked as permanently failed and requires manual intervention through the dashboard.

Handling Webhook Security

Since webhooks come from external sources, verifying their authenticity prevents fraudulent status updates. NOWPayments includes an ipn_id field in each notification, which serves as a deduplication token. Store processed ipn_id values and reject duplicates to avoid processing the same payment twice.

Implement idempotency checks in your webhook handler. Check whether an order associated with the incoming order_id already exists in your database and whether its status reflects a completed payment. If the order is already fulfilled, return 200 OK without taking further action. This protects against race conditions where customers pay quickly and multiple webhook events arrive simultaneously.

Validate the payload structure before processing. Ensure required fields such as payment_id, purchase_status, and payin_hash are present and contain valid values. Reject malformed requests with a 400 Bad Request response so the sender can investigate the issue. Log all webhook deliveries for audit purposes, including the full payload, response code, and processing result.

Checking Payment Status Manually

While webhooks handle most status updates automatically, there are cases where manual verification is necessary. A customer might share a transaction screenshot showing payment, or a webhook might fail due to network issues on your end. The status check endpoint allows you to query the current state of any payment using its ID.

GET /v1/payment/{payment_id}

This returns the full payment object including all status history, transaction hashes, and timestamps. Compare the returned purchase_status against your internal records. If the API reports finished but your system shows the order as unpaid, trigger a reconciliation process that updates the order and fulfills it immediately.

You can also retrieve all payments associated with a specific order_id by passing it as a query parameter. This is useful when debugging discrepancies or when an order was created without a custom order_id and you need to locate it through other means.

Common Integration Patterns

Successful integrations follow a consistent pattern that minimizes errors and maximizes reliability. Start by creating the invoice inside the same transaction that creates the corresponding order in your database. This ensures both records exist together and prevents orphaned payments.

Store the NOWPayments order_id and payment_id alongside your internal order reference. These identifiers become essential when correlating webhook events with your internal records. Update the order status to pending_payment immediately after invoice creation and display the payment page to the customer.

On webhook receipt, perform the following sequence: validate the payload, check for duplicates, verify the status indicates completion, update your database, and fulfill the order. Execute these steps atomically so partial failures do not leave your system in an inconsistent state. Send a confirmation email or push notification only after the database update succeeds.

For refunds, use the refund endpoint to initiate a return of funds to the customer’s wallet. Provide the original payment_id and optionally specify a partial or full refund amount. The refund status appears in subsequent webhook notifications and should be reflected in your order history.