Security Guide

Security is foundational to Neutron. This guide covers best practices for keeping your integration secure.

Core Principles

1. Authenticated access -- All endpoints require HMAC-SHA256 signature authentication
2. Minimal data exposure -- We don't store what we don't need
3. Auditability -- Every action is logged and traceable
4. HTTPS only -- All API endpoints enforce TLS encryption

Protect Your Secrets

Verify Webhook Signatures

Always verify the X-Neutronpay-Signature header before processing webhook events:

const crypto = require('crypto');

function verifyWebhook(requestBody, signatureHeader, webhookSecret) {
  const expected = crypto
    .createHmac('sha256', webhookSecret)
    .update(requestBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signatureHeader),
    Buffer.from(expected)
  );
}

Never process unverified webhooks -- an attacker could send fake payment confirmations.

Handle Tokens Properly

Access tokens expire. Implement automatic refresh:

class NeutronClient {
  async getToken() {
    if (!this.token || Date.now() > this.tokenExpiry - 300000) {
      await this.refreshToken();
    }
    return this.token;
  }
}

Rate Limits

Implement exponential backoff when rate limited (HTTP 429):

async function requestWithRetry(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 429) {
        await new Promise(r => setTimeout(r, Math.pow(2, i) * 1000));
      } else throw err;
    }
  }
}

Data Handling

What Neutron stores: Transaction records, wallet addresses and balances, API access logs.

What Neutron does NOT store: Full KYC documents (processed, not retained), your API secret (only the key), customer PII beyond compliance requirements.

Production Security Checklist

• API secrets in environment variables or secret manager
• Webhook signatures verified on every callback
• Token refresh logic implemented
• Rate limit handling with exponential backoff
• Error logging without exposing secrets
• HTTPS enforced everywhere
• API key rotation scheduled periodically

Report a Vulnerability

Found a security issue? Email [email protected] with a description, steps to reproduce, and potential impact. We respond within 48 hours.