NOWPayments

You are integrating NOWPayments (the non-custodial crypto payment gateway) into a [Django / Next.js / etc.] application.

## IMPORTANT JURISDICTIONAL CONTEXT — READ BEFORE INTEGRATING
Section 4.1 of the NOWPayments Terms of Service explicitly prohibits use by United States citizens or residents, residents of countries subject to United Nations sanctions, and residents of countries where cryptocurrency use is forbidden by law. If your merchant is US-based, stop here and use BitPay, Coinbase Business, or a fiat processor with a crypto add-on instead. Do not build a NOWPayments integration for a US merchant — use will be a breach of the user agreement with no liability recourse beyond USD 500.

## Setup
1. Register a merchant account at https://nowpayments.io/ and complete the email verification.
2. In the dashboard, Store Settings → API Keys: create an API key. Store it as `NOWPAYMENTS_API_KEY`.
3. In Store Settings → IPN Callbacks: set an IPN secret. Store it as `NOWPAYMENTS_IPN_SECRET`. This is a DIFFERENT secret from the API key; both are required.
4. If you need Mass Payouts or Custody endpoints, record the account email and 2FA setup; Mass Payouts requires a JWT bearer token obtained via POST /v1/auth with email + password, rotated hourly.
5. Base URLs:
   - Production: `https://api.nowpayments.io/v1`
   - Sandbox: `https://api-sandbox.nowpayments.io/v1` (use the sandbox dashboard at https://sandbox.nowpayments.io/ for test keys and fake networks).
6. Choose a settlement strategy: non-custodial wallet(s) per coin, or opt-in Custody if you need balance management / fiat off-ramp. For most integrations, non-custodial direct-to-wallet is the safer default.
7. Strongly recommended: set the default settlement currency to USDT or USDC in the dashboard to avoid BTC/ETH price volatility between checkout and confirmation.

## Authentication

```python
import requests
from django.conf import settings

BASE = "https://api.nowpayments.io/v1"
HEADERS = {
    "x-api-key": settings.NOWPAYMENTS_API_KEY,
    "Content-Type": "application/json",
}
```

For Mass Payouts / Custody, add a JWT bearer token obtained from POST /v1/auth (email + password) and refresh it hourly — do not hardcode it.

## Recommended Integration: Hosted Invoice
The simplest, lowest-risk flow is to create an invoice server-side and redirect the buyer to the NOWPayments-hosted checkout.

```python
import requests

def create_invoice(amount_usd, order_id, product_name):
    response = requests.post(
        f"{BASE}/invoice",
        headers=HEADERS,
        json={
            "price_amount": float(amount_usd),
            "price_currency": "usd",
            "pay_currency": "usdt",  # recommend stablecoin settlement
            "order_id": str(order_id),
            "order_description": product_name,
            "ipn_callback_url": "https://yoursite.com/webhooks/nowpayments/",
            "success_url": "https://yoursite.com/payment-success/",
            "cancel_url": "https://yoursite.com/payment-cancelled/",
            "is_fixed_rate": True,   # locks crypto amount at quote time
            "is_fee_paid_by_user": False,
        },
        timeout=15,
    )
    response.raise_for_status()
    data = response.json()
    # data["invoice_url"] — redirect the buyer here
    # data["id"] — store to reconcile with IPN webhooks
    return data
```

## IPN Webhook Handling (CRITICAL — non-standard signing)
Never trust the browser redirect. Treat only IPN notifications as authoritative, and verify the signature on every request.

**Signature scheme:** HMAC-SHA512 of the request body after it has been parsed as JSON, its keys recursively sorted alphabetically, and re-stringified with `JSON.stringify` (no extra whitespace). The signature is delivered in the `x-nowpayments-sig` header. This is NOT a signature over the raw body — verifying against the raw body will always fail.

```python
import hmac, hashlib, json
from django.http import HttpResponse, HttpResponseBadRequest
from django.views.decorators.csrf import csrf_exempt
from django.conf import settings

def _sorted_canonical(obj):
    if isinstance(obj, dict):
        return {k: _sorted_canonical(obj[k]) for k in sorted(obj)}
    if isinstance(obj, list):
        return [_sorted_canonical(x) for x in obj]
    return obj

@csrf_exempt
def nowpayments_webhook(request):
    raw_body = request.body
    signature = request.META.get("HTTP_X_NOWPAYMENTS_SIG", "")
    if not signature:
        return HttpResponseBadRequest("Missing signature")

    try:
        parsed = json.loads(raw_body)
    except json.JSONDecodeError:
        return HttpResponseBadRequest("Invalid JSON")

    canonical = json.dumps(_sorted_canonical(parsed), separators=(",", ":"))
    expected = hmac.new(
        settings.NOWPAYMENTS_IPN_SECRET.encode(),
        canonical.encode(),
        hashlib.sha512,
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        return HttpResponseBadRequest("Invalid signature")

    payment_id = parsed["payment_id"]
    status = parsed["payment_status"]
    order_id = parsed.get("order_id")

    # Idempotency: track processed (payment_id, status) pairs
    if WebhookEvent.objects.filter(payment_id=payment_id, status=status).exists():
        return HttpResponse(status=200)

    if status == "finished":
        fulfill_order(order_id, parsed)
    elif status == "partially_paid":
        handle_partial(order_id, parsed)  # decide: partial-deliver, chase, or refund
    elif status in ("failed", "expired", "refunded"):
        mark_order_failed(order_id, status)

    WebhookEvent.objects.create(payment_id=payment_id, status=status)
    return HttpResponse(status=200)
```

## Payment Status State Machine
Expect these `payment_status` values and handle each idempotently:
- `waiting` — invoice created, no funds seen yet
- `confirming` — funds detected onchain, awaiting confirmations
- `confirmed` — confirmations reached, internal processing
- `sending` — forwarding to the merchant's wallet
- `finished` — settled to merchant wallet (fulfill the order here)
- `partially_paid` — customer underpaid; funds are already yours but short of the invoiced total. Decide per-order whether to partial-deliver, chase, or refund.
- `failed` — terminal failure
- `refunded` — you or ops initiated a refund
- `expired` — invoice expired before payment (default 1 hour)

## Security Best Practices
- Never expose `NOWPAYMENTS_API_KEY` or `NOWPAYMENTS_IPN_SECRET` in client-side code, logs, or CI build artifacts.
- Always verify the IPN signature using the sort-then-stringify canonicalization described above.
- Use `is_fixed_rate: true` on invoices to lock the crypto amount at quote time.
- Default `pay_currency` to `usdt` or `usdc` unless the merchant explicitly wants native-asset settlement.
- Enable dashboard 2FA, wallet whitelisting, and IP whitelisting.
- Withdraw balances (including any Custody balance) to a self-custody wallet regularly — do NOT treat the dashboard as a bank account, given the broad ToS termination clauses.
- Rotate `NOWPAYMENTS_API_KEY` if it ever leaks; the dashboard supports immediate revocation.

## Testing
- Register a sandbox account at https://sandbox.nowpayments.io/ — it issues separate API and IPN keys and simulates transactions on testnets.
- Use the dashboard's 'Send test IPN' button to validate your signature verification and state-machine handling without a live payment.
- Write replay tests that fire the same `(payment_id, status)` pair twice and assert the fulfillment side effect runs exactly once.
- Test `partially_paid` explicitly — it is the most common edge case in production and the ToS makes clear NOWPayments will not refund it for you.

## Common Gotchas
- **Signature failures:** You are almost certainly signing the raw body. NOWPayments signs the canonicalized (sorted keys, re-stringified) JSON. See the verifier above.
- **Wrong network deposits:** USDT exists on TRC-20, ERC-20, BEP-20, Solana, and more. Make the network explicit in your checkout UI and use the Wrong-Asset Deposits auto-processing in the dashboard.
- **Partially-paid payments:** NOWPayments does not auto-refund them because the funds are already on your wallet. Your handler must decide what to do.
- **Weekend support:** support is slow on weekends. Design your IPN handler to auto-recover as many edge cases as possible so you rarely need a live support ticket.
- **US residents:** the service is prohibited for them per Section 4.1 of the ToS. Do not ship a US integration.
- **Invoice expiration:** default 1 hour — handle `expired` gracefully, and show the user a clear 'create a new invoice' CTA.
- **Two secrets, not one:** the API key and the IPN secret are different values — mixing them is the second-most-common integration bug.
- **JWT for Mass Payouts / Custody:** these endpoints require a separate bearer token from POST /v1/auth that rotates hourly; do not try to authenticate them with just x-api-key.