168 lines
4.5 KiB
Markdown
168 lines
4.5 KiB
Markdown
# NOWPayments IPN Listener
|
|
|
|
A TypeScript Express application for receiving and processing Instant Payment Notifications (IPN) from NOWPayments.
|
|
|
|
## Features
|
|
|
|
- ✅ Secure IPN signature validation using HMAC SHA512
|
|
- ✅ TypeScript for type safety
|
|
- ✅ Handles all NOWPayments payment statuses
|
|
- ✅ MySQL/MariaDB database integration
|
|
- ✅ Automatic payment processing: moves finished payments from `pending_orders` to `sales`
|
|
- ✅ Transaction-safe database operations
|
|
- ✅ Error handling and logging
|
|
|
|
## Setup
|
|
|
|
### 1. Install Dependencies
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### 2. Configure Environment Variables
|
|
|
|
Copy `.env.example` to `.env` and fill in your NOWPayments IPN Secret Key:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` and configure:
|
|
|
|
**NOWPayments IPN Secret Key:**
|
|
- Go to NOWPayments Dashboard → Store Settings → IPN Secret Key
|
|
- Generate a new key if you don't have one
|
|
- Add it to the `.env` file
|
|
|
|
**Database Configuration:**
|
|
- Set your MySQL/MariaDB connection details:
|
|
- `DB_HOST` - Database host (default: localhost)
|
|
- `DB_PORT` - Database port (default: 3306)
|
|
- `DB_USER` - Database username
|
|
- `DB_PASSWORD` - Database password
|
|
- `DB_NAME` - Database name (default: cbd420)
|
|
|
|
### 3. Build the Project
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
### 4. Run the Server
|
|
|
|
**Development mode (with auto-reload):**
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
**Production mode:**
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
The server will start on port 3000 (or the port specified in your `.env` file).
|
|
|
|
## Endpoints
|
|
|
|
### POST `/ipn`
|
|
Receives IPN notifications from NOWPayments. This endpoint:
|
|
- Validates the request signature
|
|
- Processes payment status updates
|
|
- Returns 200 OK to acknowledge receipt
|
|
|
|
### GET `/health`
|
|
Health check endpoint to verify the server is running.
|
|
|
|
## IPN Callback URL Setup
|
|
|
|
When creating a payment via the NOWPayments API, include the `ipn_callback_url` parameter:
|
|
|
|
```javascript
|
|
{
|
|
"price_amount": 100,
|
|
"price_currency": "usd",
|
|
"pay_currency": "btc",
|
|
"ipn_callback_url": "https://yourdomain.com/ipn",
|
|
// ... other parameters
|
|
}
|
|
```
|
|
|
|
## Payment Statuses
|
|
|
|
The listener handles the following payment statuses:
|
|
|
|
- `waiting` - Payment is waiting
|
|
- `confirming` - Payment is being confirmed on blockchain
|
|
- `confirmed` - Payment confirmed on blockchain
|
|
- `sending` - Payment is being sent
|
|
- `partially_paid` - Payment partially received
|
|
- `finished` - Payment completed successfully
|
|
- `failed` - Payment failed
|
|
- `refunded` - Payment refunded
|
|
- `expired` - Payment expired
|
|
|
|
## Database Integration
|
|
|
|
The application automatically integrates with your MySQL/MariaDB database. When a payment status is `finished`, the system will:
|
|
|
|
1. **Validate the payment** - Check if the payment exists in `pending_orders`
|
|
2. **Create a sale record** - Insert the payment into the `sales` table
|
|
3. **Remove pending order** - Delete the record from `pending_orders`
|
|
|
|
All operations are performed within a database transaction to ensure data consistency.
|
|
|
|
### Database Schema
|
|
|
|
The application expects the following tables (as defined in `cbd420(1).sql`):
|
|
|
|
- **`pending_orders`** - Stores pending payment orders
|
|
- `payment_id` (unique) - NOWPayments payment ID
|
|
- `order_id` (unique) - Your order ID
|
|
- `drop_id` - Reference to drops table
|
|
- `buyer_id` - Reference to buyers table
|
|
- `size` - Order size
|
|
- `price_amount` - Payment amount
|
|
- `price_currency` - Payment currency
|
|
|
|
- **`sales`** - Stores completed sales
|
|
- `drop_id` - Reference to drops table
|
|
- `buyer_id` - Reference to buyers table
|
|
- `size` - Sale size
|
|
- `payment_id` - NOWPayments payment ID
|
|
|
|
### Payment Processing Flow
|
|
|
|
1. Payment is created → Record inserted into `pending_orders`
|
|
2. IPN notification received → Signature validated
|
|
3. Payment status `finished` → Record moved from `pending_orders` to `sales`
|
|
4. Transaction committed → Payment processing complete
|
|
|
|
The system includes idempotency checks to prevent duplicate processing if the same IPN notification is received multiple times.
|
|
|
|
## Security
|
|
|
|
- All IPN requests are validated using HMAC SHA512 signature verification
|
|
- Invalid signatures are rejected with 400 Bad Request
|
|
- The IPN secret key should never be committed to version control
|
|
|
|
## Testing
|
|
|
|
You can test the IPN endpoint using tools like:
|
|
- Postman
|
|
- curl
|
|
- NOWPayments test payments
|
|
|
|
Example curl command (with test signature):
|
|
```bash
|
|
curl -X POST http://localhost:3000/ipn \
|
|
-H "Content-Type: application/json" \
|
|
-H "x-nowpayments-sig: your_signature_here" \
|
|
-d '{"payment_id":"test123","payment_status":"waiting","price_amount":100,"price_currency":"usd"}'
|
|
```
|
|
|
|
## License
|
|
|
|
ISC
|
|
|