magenettic/module-btc-payment

Bitcoin payment method for Magento 2 via BTCPay Server

dev-master 2026-06-17 14:30 UTC

Requires

• php: >=8.2
• magento/framework: >=103.0.4
• magento/module-checkout: >=100.4.4
• magento/module-config: >=101.2.4
• magento/module-payment: >=100.4.4
• magento/module-sales: >=103.0.4

MIT

README

Bitcoin Payment Method for Magento 2 via BTCPay Server

Overview

This module integrates Magento 2 with BTCPay Server, enabling customers to pay with Bitcoin (BTC) at checkout. It uses the BTCPay Server Greenfield API to create invoices, monitor payments, and handle webhook events.

Requirements

• PHP >= 8.2
• Magento 2.4.x (Community Edition)
• BTCPay Server instance (self-hosted or third-party)

Compatibility

Magento Version	Compatible
2.4.4 - 2.4.7	Yes

Installation

composer require magenettic/module-btc-payment
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

Configuration

1. Navigate to Stores → Configuration → Sales → Payment Methods.
2. Locate Bitcoin Payment (Magenettic).
3. Configure the following settings:

Setting	Description
Enabled	Enable/disable the payment method
Title	Display name at checkout
BTCPay Server URL	Base URL of your BTCPay Server
API Key	Greenfield API key with invoice creation permissions
Store ID	BTCPay Store ID
Webhook Secret	HMAC-SHA256 secret for webhook validation
Sandbox Mode	Use BTCPay Testnet for development
Payment Timeout	Invoice expiration time in seconds (default: 900)
New Order Status	Initial order status after checkout

1. Configure the Webhook URL (displayed in settings) in your BTCPay Server: Server Settings → Webhooks.

Architecture

Magenettic_BtcPayment/
├── Block/                           # Layout blocks (form, info, config)
├── Controller/Webhook/              # Webhook endpoint (HTTP POST)
├── Cron/                            # Cron job for pending payments
├── Gateway/
│   ├── Config/                      # Payment gateway configuration
│   ├── Http/                        # HTTP client and transfer factory
│   ├── Request/                     # API request builders
│   ├── Response/                    # API response handlers
│   └── Validator/                   # Request/response validators
├── Helper/                          # Utility helpers
├── Model/
│   ├── BtcTransaction.php           # Transaction model
│   ├── Config/                      # Scope config and source models
│   ├── ResourceModel/               # Database resource models
│   └── Ui/                          # Checkout config provider
├── Observer/                        # Event observers
├── Setup/Patch/Data/                # Data patches (order statuses)
├── etc/                             # Module configuration (di, events, etc.)
└── view/                            # Frontend and admin templates

Payment Flow

1. Customer selects Bitcoin Payment at checkout and places the order.
2. Module creates an invoice on BTCPay Server via Greenfield API.
3. Order status is set to btc_pending (Awaiting Bitcoin Payment).
4. Customer is redirected to the BTCPay checkout page to complete payment.
5. BTCPay Server sends webhook events as payment status changes.
6. Module updates order status accordingly:
   • InvoicePaid → btc_confirmed
   • InvoiceSettled → processing
   • InvoiceExpired → btc_expired (order cancelled)

Order Statuses

Status Code	Label	Magento State
btc_pending	Awaiting Bitcoin Payment	new
btc_confirmed	Bitcoin Payment Confirmed	processing
btc_processing	Bitcoin Processing	processing
btc_expired	Bitcoin Payment Expired	canceled
btc_refunded	Bitcoin Refunded	closed

Cron Jobs

• CheckPendingPayments — Automatically cancels expired orders (runs periodically).

Extensibility

• Event: btcpayment_webhook_received — dispatched when a webhook is received
• Plugins/interceptors: all public methods in Gateway classes are extensible
• Database schema: magenettic_btcpayment_transaction table stores all invoice data

Security

• API keys and webhook secrets are stored encrypted (backend_model="Magento\Config\Model\Config\Backend\Encrypted).
• CSP whitelist configured for BTCPay Server hosts.
• Webhook endpoint bypasses CSRF protection (CsrfAwareActionInterface).

Uninstallation

bin/magento module:disable Magenettic_BtcPayment
composer remove magenettic/module-btc-payment
bin/magento setup:upgrade
bin/magento setup:di:compile

Support

Report issues at: https://github.com/magenettic/magento2-btcpay/issues

License

MIT

Copyright

Copyright (c) 2026 Magenettic