How Do You Connect Your BTCPay Server to a Third-Party Fiat Settlement Provider?
Connecting a self-hosted BTCPay Server to a third-party fiat settlement provider allows you to automatically convert incoming cryptocurrency payments to fiat currency (like USD, EUR, or GBP) and have those funds settled to your bank account. This setup bridges the gap between accepting crypto directly via your own node and receiving traditional currency without manually moving funds through an exchange.
Why Connect a Fiat Settlement Provider to BTCPay Server
BTCPay Server processes payments entirely on your own infrastructure. When a customer pays an invoice, the funds arrive in your wallet. Without a settlement provider, you must manually transfer those coins to an exchange, sell them, and withdraw the fiat to your bank. A settlement provider automates this pipeline:
- It monitors your BTCPay Server for completed payments.
- It receives the crypto (or access to it) and executes a conversion.
- It sends the fiat proceeds to your linked bank account, usually on a recurring schedule or per transaction.
This reduces operational overhead and eliminates the need to hold volatile crypto balances for longer than necessary.
What a Settlement Provider Needs from Your BTCPay Server
Most third-party fiat settlement providers require a few pieces of information to connect to your BTCPay Server:
- Your BTCPay Server URL - The public address where your instance is accessible. If your server is behind a firewall or not exposed to the internet, the provider cannot reach it.
- API credentials - BTCPay Server supports API keys with granular permissions. You will generate a key that grants the provider read access to invoice data and, in some configurations, permission to mark invoices as settled or to trigger a payout.
- A webhook endpoint - BTCPay Server can send HTTP callbacks when invoice statuses change (for example, when a payment is confirmed). The settlement provider gives you a webhook URL to enter in your BTCPay Server settings.
Some providers also require you to install a plugin or application on the same server that communicates with BTCPay’s internal API. Check the provider’s documentation for the exact method.
General steps to connect
The exact process varies by provider, but the high-level sequence is similar:
- Sign up for a fiat settlement service that explicitly supports BTCPay Server integration. Provide your business details and bank account information for fiat payouts.
- Generate an API key in BTCPay Server with appropriate permissions. Typically you need
btcpay.store.canviewinvoicesand possiblybtcpay.store.cancreateinvoice. Do not grant broader permissions than necessary. - Create a webhook in BTCPay Server for the store you want to settle. Enter the endpoint URL provided by the settlement service. Select the events to trigger the webhook, usually “Invoice received payment” and “Invoice settled.”
- Configure the settlement provider’s dashboard with your BTCPay Server URL and the API key you generated. Some providers will test the connection automatically.
- Set your settlement preferences - choose whether to convert every payment immediately, batch conversions daily, or set a minimum threshold amount before conversion.
- Test with a small payment - send a minimal amount to an invoice to confirm the webhook fires, the provider detects the payment, and the conversion and bank transfer work as expected.
Important Considerations
Security of API Keys and Webhooks
- Use a dedicated API key for each settlement provider. If you need to revoke access later, you can delete that single key without affecting other integrations.
- Webhook secrets (if provided by BTCPay Server) should be kept private. The settlement provider will use this secret to sign callback payloads so you can verify they are genuine.
- If your BTCPay Server is accessible from the internet, ensure it is secured with HTTPS and strong administrative credentials.
Settlement timing and fees
- Conversion rates are typically based on the market rate at the moment the provider receives the crypto. There is usually a small spread or flat fee for the conversion.
- Bank settlement can take one to three business days, depending on the provider and your jurisdiction.
- Some providers charge a monthly fee or a per-transaction fee. Review the pricing structure before committing.
What happens to unsettled payments
If a payment arrives but the settlement provider fails to process it (for example, due to a network error or an expired API key), the crypto remains in your BTCPay Server wallet. You can still manually export it to an exchange and convert it yourself. The automation is a convenience, not a requirement for receiving funds.
Regulatory and compliance factors
- Fiat settlement providers are typically regulated financial entities. They will require KYC (Know Your Customer) documentation from your business before activation.
- Depending on your jurisdiction, converting crypto to fiat may trigger tax reporting obligations. Your accounting setup should record the conversion event separately from the initial crypto payment.
- Some providers impose limits on how much crypto can be settled per day or per month. Check these thresholds against your expected transaction volume.
Troubleshooting common connection issues
- Webhook not firing - Verify the webhook URL is entered correctly in BTCPay Server and that your server can reach the internet. Check the webhook logs in BTCPay Server for failed deliveries.
- API key rejected - Confirm the key has the correct store permissions and has not expired. Regenerate the key if necessary.
- Provider cannot reach your server - If your BTCPay Server is behind a NAT or firewall, you may need to use a reverse proxy or a tunnel service. Some providers support connecting to a server that is not publicly accessible by using a polling method instead of webhooks.
When this setup makes sense
Connecting a fiat settlement provider is most useful for businesses that process a regular volume of crypto payments and need to convert to fiat automatically for cash flow, payroll, or supplier payments. It is less necessary for occasional sales or for businesses that prefer to hold crypto as an asset.
Not financial advice. unidexai.xyz publishes market data and general information about digital assets. Crypto assets are volatile and you can lose everything you put in. Nothing here is a recommendation to buy, sell or hold, and we make no price predictions.
Prices are sourced from third parties and may be delayed or wrong. Verify anything you intend to act on against a primary source.