NOWPayments Plugin

A cryptocurrency payment gateway plugin for Vendure that integrates with NOWPayments.io, enabling your store to accept payments in Bitcoin, Ethereum, and 100+ other cryptocurrencies.

Features

✅ Cryptocurrency Payments: Accept payments in Bitcoin, Ethereum, Litecoin, and 100+ other cryptocurrencies
✅ Dual Payment Modes: Support for both direct payment links and invoices
✅ Secure IPN Handling: Instant Payment Notification webhook processing with HMAC signature verification
✅ Multiple Payment Statuses: Handle finished, partially_paid, confirming, confirmed, sending, and failed payments
✅ Sandbox Mode: Test your integration safely with sandbox endpoints
✅ Configurable Options: Customizable invoice prefixes, total calculations, and debug settings
✅ Full IPN Storage: Complete IPN response storage with outcome_currency tracking
✅ TypeScript Support: Full type definitions for excellent developer experience

Installation

Configuration

Add the plugin to your Vendure config:

NOWPayments Setup

1. Create a NOWPayments Account

Sign up at nowpayments.io
Complete KYC verification
Get your API key from the dashboard

2. Configure IPN (Instant Payment Notification)

Set your IPN URL to: https://yourdomain.com/nowpayments/ipn
Get your IPN secret from the NOWPayments dashboard
Ensure your server is accessible via HTTPS

3. Environment Variables

Usage

Payment Flow

Customer selects NOWPayments during checkout
Payment URL is generated (direct link or invoice)
Customer is redirected to NOWPayments payment page
Customer pays with their chosen cryptocurrency
NOWPayments sends IPN to your server
Order status is updated based on payment status

Payment Statuses

Status	Order State	Description
`finished`	PaymentSettled	Payment completed successfully
`partially_paid`	PaymentAuthorized	Partial payment received
`confirming`	PaymentAuthorized	Payment is being confirmed
`confirmed`	PaymentAuthorized	Payment confirmed on blockchain
`sending`	PaymentAuthorized	Payment is being sent
`waiting`	PaymentAuthorized	Payment is waiting for user action
`expired`	PaymentDeclined	Payment has expired
`failed`	PaymentDeclined	Payment failed

Configuration Options

Option	Type	Required	Default	Description
`apiKey`	string	✅	-	Your NOWPayments.io API key
`ipnSecret`	string	✅	-	Your NOWPayments.io IPN secret
`host`	string	❌	'http://localhost:3000'	Your Vendure server host
`sandbox`	boolean	❌	false	Enable sandbox mode for testing
`useInvoices`	boolean	❌	false	Use invoices instead of direct payment links
`invoicePrefix`	string	❌	'VC-'	Prefix for invoice numbers (must not end with digit)
`simpleTotal`	boolean	❌	false	Use simple total calculation
`allowZeroConfirm`	boolean	❌	true	Allow zero confirmation payments
`formSubmissionMethod`	boolean	❌	true	Use form submission method
`debugEmail`	string	❌	-	Email for debug notifications
`debugPostUrl`	string	❌	-	URL for debug POST notifications
`is_fixed_rate`	boolean	❌	false	Use fixed rate pricing for cryptocurrency conversions
`is_fee_paid_by_user`	boolean	❌	false	Whether transaction fees are paid by the user

Supported Cryptocurrencies

Bitcoin (BTC)
Ethereum (ETH)
Litecoin (LTC)
Bitcoin Cash (BCH)
Ripple (XRP)
Cardano (ADA)
Polkadot (DOT)
Chainlink (LINK)
And 100+ more...

API Extensions

The plugin extends the Vendure GraphQL API with the following:

Payment Method

nowpayments - The payment method handler for NOWPayments

IPN Endpoint

POST /nowpayments/ipn - Webhook endpoint for NOWPayments IPN callbacks

Payment Flow URLs

The plugin automatically generates the following URLs for payment flows:

Success URL: {host}/checkout/confirmation/{orderCode} - Redirected to after successful payment
Cancel URL: {host}/checkout/cancel/{orderCode} - Redirected to if payment is cancelled
IPN URL: {host}/nowpayments/ipn - Webhook endpoint for payment notifications

Note: Replace {host} with your actual Vendure server URL (e.g., https://yourdomain.com).

Security Features

HMAC Signature Verification: All IPN requests are verified using SHA512 HMAC
Order Validation: Payment amounts and currencies are validated
Secure API Communication: All API calls use HTTPS
Error Logging: Comprehensive error logging for debugging

Development

Building the Plugin

Running Tests

Development Mode

Troubleshooting

Common Issues

IPN not received:
- Check your server is accessible via HTTPS
- Verify IPN URL is correct in NOWPayments dashboard
- Check server logs for errors
Invalid signature errors:
- Verify IPN secret is correct
- Ensure HMAC calculation is working properly
- Check for encoding issues
Payment not settling:
- Check payment status in NOWPayments dashboard
- Verify order ID format matches expected pattern
- Review server logs for processing errors
Sandbox mode issues:
- Ensure NOWPAYMENTS_SANDBOX=true is set
- Use sandbox API keys for testing
- Check sandbox endpoints are being used

Debug Mode

Enable debug mode by setting the environment variable:

This will log detailed information about payment processing and IPN handling.

Support

For support with this plugin:

Check the Vendure documentation
Review the NOWPayments documentation
Check the server logs for error details
Contact support with specific error messages and logs

License

This plugin is licensed under the MIT License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Changelog

See CHANGELOG.md for a list of changes between versions.

Add Release commit