Building a Self-Hosted Cryptocurrency Payment Platform with BTCPay on AWS
BTCPay Server is an self-hosted cryptocurrency payment processor that enables merchants to generate invoices, provide secure checkout experiences, and receive payments directly into their own wallets.
As digital payments continue to evolve, businesses are exploring alternatives to traditional payment processors. Cryptocurrency payments offer another way to accept payments globally, but they also introduce architectural challenges around security, wallet management, infrastructure reliability, and operational monitoring.
BTCPay Server is an open-source, self-hosted cryptocurrency payment processor that enables merchants to create invoices, provide checkout experiences, and receive payments directly into wallets they control.
Unlike custodial payment intermediaries, BTCPay Server does not hold merchant funds. This model gives merchants greater control over their payment infrastructure and reduces their dependence on third-party payment processors.
In this article, we'll explore how to build a secure, scalable BTCPay Server deployment on Amazon Web Services (AWS), using Amazon Elastic Kubernetes Service (Amazon EKS), Terraform, Helm, and AWS-native security services.
The goal is to demonstrate how platform engineering principles can be applied to self-hosted cryptocurrency payment infrastructure.
1. Architecture Overview
A production deployment should separate the payment application, blockchain connectivity, persistent storage, and infrastructure management.
Core components
- Amazon EKS: Runs BTCPay Server and its supporting workloads.
- Application Load Balancer (ALB): Provides HTTPS access to the merchant checkout interface and administrative portal.
- AWS Load Balancer Controller: Integrates Kubernetes ingress resources with AWS load balancing.
- Amazon EBS: Provides persistent block storage for workloads that require durable local volumes.
- Amazon EFS, where appropriate: Provides shared filesystem storage for compatible workloads.
- AWS Secrets Manager: Stores sensitive configuration and credentials.
- Amazon CloudWatch: Collects logs, metrics, and operational signals.
- Terraform: Provisions AWS infrastructure and manages infrastructure configuration.
- Helm: Packages and deploys Kubernetes applications.
- Bitcoin Core: Provides blockchain synchronization, transaction validation, and access to the Bitcoin network.
- BTCPay Server: Creates invoices, manages payment workflows, and monitors incoming payments.
Bitcoin Core is relevant to a Bitcoin-focused deployment. Additional cryptocurrencies require their respective supported node or integration architecture.
Request and payment flow
The architecture follows this general flow:
- A customer visits the merchant's checkout page.
- BTCPay Server creates an invoice associated with the merchant's store.
- The checkout page displays the payment instructions.
- The customer broadcasts a cryptocurrency transaction.
- The blockchain node observes the transaction and provides the relevant data to BTCPay Server.
- BTCPay Server updates the invoice status as the payment progresses through the required confirmation states.
- The merchant's application receives payment notifications through supported integrations or webhooks.
Important distinction: The customer does not pay an AWS account or a custodial BTCPay Server wallet. Funds are directed to the merchant's configured wallet addresses. The merchant remains responsible for wallet security, private keys, transaction policies, and recovery procedures.
2. Why Deploy BTCPay Server on AWS?
AWS provides infrastructure services that can support a reliable, observable, and maintainable payment platform.
Infrastructure as Code
Terraform allows teams to define and version-control infrastructure resources, including:
- Virtual Private Clouds and subnets.
- Amazon EKS clusters and node groups.
- Security groups and IAM permissions.
- Application load balancing and DNS integration.
- Persistent storage.
- Logging and monitoring resources.
Infrastructure changes can be reviewed before deployment, reducing configuration drift and making environments easier to reproduce.
Kubernetes orchestration
Amazon EKS provides managed Kubernetes control-plane operations, workload scheduling, health monitoring, and integration with AWS infrastructure.
Kubernetes can simplify application lifecycle management, but it does not automatically make a payment platform highly available. Stateful blockchain workloads, persistent volumes, database consistency, and recovery procedures require deliberate design.
Security and observability
AWS provides services for identity management, secret storage, network isolation, encryption, and operational monitoring.
These capabilities help teams establish consistent security controls around the application and its supporting infrastructure.
For an overview of the platform, see the official Amazon EKS documentation .
3. Design the Network and Security Boundaries
Payment infrastructure should use a network design that limits unnecessary exposure.
A recommended baseline includes:
- Private subnets for EKS worker nodes and stateful workloads.
- Public access only through explicitly approved entry points.
- HTTPS for customer-facing checkout traffic.
- Restricted administrative access.
- Security groups that allow only required communication paths.
- Kubernetes NetworkPolicies where supported by the selected CNI and policy implementation.
Public and private endpoints
The merchant checkout interface must be reachable by customers if online payments are being accepted.
Administrative interfaces should be restricted where possible, using an internal endpoint, VPN, identity-aware access controls, or another approved administrative access pattern.
Bitcoin nodes also require carefully planned connectivity. A node may need outbound connectivity to discover peers and synchronize blockchain data. Inbound peer-to-peer connectivity is optional for some configurations and should be enabled only when required by the operational design.
Do not expose RPC interfaces, database ports, management endpoints, or internal service ports to the public internet.
TLS
Use AWS Certificate Manager with an Application Load Balancer to provide HTTPS for customer-facing endpoints.
If TLS terminates at the load balancer, secure the connection between the load balancer and backend workloads as appropriate for the threat model and compliance requirements.
4. Deploy BTCPay Server with Helm
Helm provides a repeatable mechanism for deploying Kubernetes applications and managing their configuration.
Before selecting a chart, verify that it supports the required BTCPay Server version, deployment mode, persistent storage, and supporting services. A chart's existence does not guarantee that it is officially maintained or production-ready.
For production use, pin the Helm chart and container image versions.
Retrieve the BTCPay Server image
For example, the following command retrieves a specific BTCPay Server image version:
1
docker pull btcpayserver/btcpayserver:2.4.5Before deploying this version, verify that it remains an approved and supported release for your environment.
Example Helm deployment workflow
First, create a dedicated namespace:
1
kubectl create namespace btcpayThen validate the chart repository and chart version you intend to use:
1
2
helm repo list
helm search repo btcpay --versionsIf you use a maintained, compatible chart, deploy it with an environment-specific values file:
1
2
3
helm upgrade --install btcpay <verified-chart-reference> \
--namespace btcpay \
--values helm/btcpay-values.yamlThe chart reference above is a placeholder, not an actual repository URL. Replace it with a verified chart reference and validate its values schema before deployment.
A complete BTCPay Server deployment may require more than a single application container. Depending on the selected deployment model, supporting components can include Bitcoin Core, PostgreSQL, a reverse proxy, and other services.
Do not assume that a generic Helm chart deploys all of these components or configures them securely by default.
5. Manage Persistent Storage for Blockchain Data
Blockchain nodes are stateful applications. Their data directories can grow significantly over time, making storage capacity, disk performance, and recovery planning essential.
Amazon EBS
Amazon EBS is suitable for workloads that require durable block storage attached to a node.
For a Kubernetes deployment, use a suitable EBS CSI driver and StorageClass. A
gp3 volume is a reasonable starting point for many workloads, although the required capacity and performance depend on the node's data footprint and workload.Important considerations include:
- Volume capacity and expansion.
- Encryption at rest.
- IOPS and throughput requirements.
- Availability Zone placement.
- Snapshot policies.
- Restore testing.
- Pod scheduling and volume attachment behavior.
An EBS volume is typically tied to a particular Availability Zone. A replacement pod may need to be scheduled in that same zone to reattach the volume.
Bitcoin Core storage
Bitcoin Core's blockchain data should reside on persistent storage rather than a container's ephemeral filesystem.
Capacity planning should account for blockchain growth, database overhead, indexes, logs, temporary disk requirements, and recovery operations.
If you use pruning, validate that the chosen configuration supports the features and operational requirements of your BTCPay Server deployment. Do not assume that a pruned node supports every possible integration or indexing workflow.
Backups
Snapshots can help recover persistent infrastructure, but they must be integrated into a consistent backup strategy.
A production design should document:
- Which stateful components require backups.
- How application metadata is backed up.
- Whether blockchain data can be reconstructed instead of fully backed up.
- How encryption keys and wallet recovery material are protected.
- How restoration is tested.
- Which recovery time and recovery point objectives apply.
Wallet recovery material must be protected independently of ordinary Kubernetes backups. Possession of a database backup or EBS snapshot does not necessarily provide the ability to recover merchant funds.
6. Separate Application Secrets from Wallet Security
One of the most important design principles is distinguishing application credentials from cryptocurrency private keys.
AWS Secrets Manager can store application secrets such as database passwords and supported service credentials.
However, merchant wallet private keys, seed phrases, and other wallet recovery material require a dedicated security model.
A self-custodial architecture should minimize private-key exposure and avoid placing recovery phrases in:
- Terraform configuration files.
- Terraform state.
- Helm values committed to Git.
- Container images.
- Kubernetes manifests stored in source control.
- CI/CD logs.
- General-purpose application environment variables.
For an appropriate payment workflow, BTCPay Server can use wallet configurations that allow it to generate payment addresses without holding the merchant's spending keys. The exact capability depends on the supported wallet type and configuration.
Where supported, watch-only wallet integration can reduce the consequences of a compromised application environment.
Least-privilege access
Use EKS Pod Identity or IAM roles for service accounts when workloads need AWS permissions.
Grant each workload only the permissions it requires. For example, a workload that reads one application secret should not automatically have broad access to all secrets in the AWS account.
See the official AWS Secrets Manager documentation for guidance on storing and managing application secrets.
7. Configure Payment Notifications Securely
BTCPay Server can integrate with merchant applications to communicate invoice and payment status changes.
For example, an e-commerce platform may use payment notifications to update an order's payment state.
The integration should not treat every incoming transaction as immediately settled.
Instead, the merchant application should distinguish among states such as:
- Invoice created.
- Payment detected.
- Payment confirmed according to the configured policy.
- Invoice settled.
- Invoice expired or otherwise invalid for the intended transaction.
The exact status names and transitions depend on the BTCPay Server version and integration.
Webhook security
When implementing payment notifications:
- Validate incoming notifications using the supported authentication or verification mechanism.
- Associate each invoice with the correct merchant order.
- Make event processing idempotent so retries do not duplicate fulfillment.
- Verify payment status through the trusted BTCPay Server integration.
- Apply confirmation policies appropriate to the transaction value and risk.
- Record audit events for order and payment state changes.
A payment notification should trigger a controlled state transition, not blindly authorize fulfillment based on an unverified HTTP request.
8. Improve Reliability and Scalability
Not every component of a cryptocurrency payment platform scales in the same way.
Application workloads
Stateless application components can often be scaled horizontally, provided the selected BTCPay Server deployment mode supports multiple replicas and its state-management requirements are satisfied.
Before adding replicas, validate:
- Session and configuration consistency.
- Shared application state.
- Background job behavior.
- Database connection limits.
- Payment notification delivery.
- Version compatibility during rolling upgrades.
Stateful services
Blockchain nodes and databases require separate scaling and recovery strategies.
Increasing the number of application pods does not increase blockchain synchronization speed automatically. Performance can instead be limited by disk throughput, available storage, CPU, peer connectivity, or the database.
Availability Zones
EKS can distribute suitable application workloads across multiple Availability Zones. However, stateful workloads backed by zonal EBS volumes require careful scheduling and failover planning.
High availability should be measured across the entire payment flow—from invoice creation through transaction observation and status updates—not just by counting healthy Kubernetes pods.
9. Monitoring and Operational Visibility
A production payment platform should provide visibility into both infrastructure health and payment processing.
Amazon CloudWatch can collect AWS infrastructure metrics and application logs. Additional monitoring can be integrated where appropriate.
Recommended signals include:
| Component | Monitoring focus |
|---|---|
| BTCPay Server | Application errors, latency, invoice processing |
| Bitcoin Core | Synchronization status, peer connectivity, RPC health |
| Kubernetes | Pod restarts, resource pressure, failed probes |
| Persistent storage | Capacity, throughput, latency, attachment errors |
| Database | Connections, query latency, storage, availability |
| Application Load Balancer | Target health, HTTP errors, request latency |
| Security | Administrative access, IAM activity, secret access |
Alerts should distinguish infrastructure failures from payment-processing delays.
For example, a blockchain node that is still synchronizing may be running successfully as a process while remaining unsuitable for reliable production payment monitoring.
Operational runbooks should cover node synchronization, database recovery, certificate renewal, application upgrades, credential rotation, and disaster recovery.
10. Automate Infrastructure Delivery with Terraform and GitOps
A repeatable deployment pipeline helps reduce configuration drift and improves change control.
A possible repository structure is:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
btcpay-platform/
├── terraform/
│ ├── providers.tf
│ ├── variables.tf
│ ├── vpc.tf
│ ├── eks.tf
│ ├── storage.tf
│ ├── iam.tf
│ ├── security-groups.tf
│ └── outputs.tf
├── helm/
│ └── btcpay-values.yaml
├── kubernetes/
│ ├── namespace.yaml
│ ├── ingress.yaml
│ └── network-policy.yaml
├── monitoring/
│ └── alerts.yaml
└── README.mdThe exact resources depend on whether supporting services are deployed inside EKS or managed separately.
A CI/CD workflow can perform the following steps:
- Validate Terraform formatting and configuration.
- Generate and review a Terraform plan.
- Validate Helm values and render manifests.
- Scan container images and Kubernetes configuration.
- Deploy to a test environment.
- Verify node synchronization and application health.
- Test invoice creation and payment notifications.
- Promote the approved configuration to production.
- Monitor the deployment and maintain a documented rollback strategy.
Argo CD or another GitOps controller can manage the Kubernetes deployment from a version-controlled repository.
Pin provider, chart, and container image versions. Protect deployment credentials, restrict production approvals, and ensure secrets are not exposed in pipeline logs.
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article