# BTCPay Server Module

https://docs.wisecp.com/de/btcpay-server-module

Connect your BTCPay Server store to accept cryptocurrency payments and follow confirmations and refund requests from WISECP.

## Reaching the Screen

Go to **Settings → Financial → Payment Gateways → All Modules** and click **BTCPay Server**: `{admin}/modules/payment?module=BTCPayServer`

## What Is on the Screen

The form connects a store and controls its payment page. Clients click **Continue to BTCPay Server** to pay on your server. The module checks payment status after a webhook or browser return.

It offers refund requests, but no card storage, automatic payments, WISECP subscriptions, installments or separate capture. BTCPay Server's own subscription features are not connected to WISECP by this module.

## Before You Configure It

Use a reachable HTTPS BTCPay Server, an account allowed to manage the store, and a configured wallet. Enable the store's intended on-chain or Lightning methods and check node synchronization, exchange rates and available payout funds.

There is no sandbox switch or connection-test button. Use a separate WISECP test system and a BTCPay testnet server/store. The server version must support the module's current Greenfield invoice and refund API.

## Fields

- **Server Address**: Required; empty by default. Your server's base HTTPS address, such as https://btcpay.example.com, without /api/v1.
- **API Key**: Required; empty by default. A Greenfield key restricted to this store, with the permissions listed below.
- **Store ID**: Required; empty by default. Copy the store identifier from its settings page/address. It must belong to the API key's scope.
- **Webhook Secret**: Empty by default; configure it for signed notifications. Without it, signature checking is skipped, although the invoice is still fetched through the API.
- **Confirmation Speed**: Defaults to Use the store setting. Choices are Fastest, no confirmation; One confirmation; Two confirmations; Six confirmations. Fastest still requires one confirmation for an RBF transaction.
- **Invoice Lifetime (Minutes)**: Optional; empty uses the store setting. Enter positive minutes to override it. The displayed 15 is an example, not the default.
- **Payment Methods**: Optional; empty offers the store's enabled methods. To restrict them, enter their exact IDs separated by commas, for example BTC-CHAIN, BTC-LN.
- **Return Automatically**: On by default. Requests an automatic return from the payment page. Returning does not replace confirmation.

**Status** enables the module. Shared commission, conversion, limits and country settings are in [Payment Modules](https://docs.wisecp.com/en/payment-modules). Copy generated **Callback URL** for notifications; **Success URL** and **Failed URL** are result addresses.

## Tasks

### Connect the Store

1. In BTCPay Server, open **Account → Manage Account → API Keys**. Create and save a key restricted to your intended store.
2. Grant invoice creation/read access. For refunds, also grant creation and management of pull payments, using the exact permissions below. Copy the generated key.
3. In WISECP, enter **Server Address**, **API Key** and **Store ID**. Enable **Status**, choose the payment-page options and click **Save Changes**.
4. Under **Payment Gateways → Initial → Enabled Module Selection**, select BTCPay Server and click **Save Changes**. The method is offered within its configured limits.

### Configure the Webhook

1. Copy the complete **Callback URL** from WISECP. In the matching BTCPay store, open **Settings → Webhooks** and create a webhook for that URL.
2. Enable invoice events, including **InvoiceSettled**, **InvoiceProcessing**, **InvoiceExpired** and **InvoiceInvalid**. Keep automatic redelivery enabled and save the webhook.
3. Copy its secret into WISECP's **Webhook Secret** and click **Save Changes**. Do not use the API key as this secret.
4. After a test payment, inspect webhook deliveries in BTCPay Server. Confirm WISECP records the matching invoice when its provider status becomes **Settled**.

### Test the Payment

1. Open an unpaid test invoice as its client and select BTCPay Server. Click **Continue to BTCPay Server**, then pay using the test server's network.
2. Match the provider invoice, amount and currency with WISECP. **New** and **Processing** leave payment open; only **Settled** closes it.
3. Test expiry, an interrupted browser return and insufficient payment. Wait for confirmations before retrying; a late settled payment may still close the invoice.
4. After successful tests, enter the mainnet server, store, API key and webhook secret. Click **Save Changes** and verify the live webhook; subsequent payments use real funds.

### Create and Complete a Refund

1. Open the paid invoice: `{admin}/invoices/detail?id={invoice}`. Under **Summary → Change Status**, select **Refunded → Refund via payment gateway** and click **Update Status**.
2. The module requests a pull payment for this invoice's collected share, including combined payments. Find that refund in BTCPay Server; give the customer its claim-page link.
3. The customer enters the refund destination and claims it. In BTCPay Server's **Payouts**, select the payout and use **Actions → Approve and send**.
4. Sign and broadcast as required by your wallet, then verify the payout reaches **completed**. WISECP's refund status alone does not prove funds arrived.

For a custom partial or excess-payment refund, use **Invoices → Details → Issue a refund** in BTCPay Server. Choose the method and amount, share the claim link and complete its payout. Track the actual amount separately; do not issue the same refund again from WISECP.

## Things to Watch

> **Refunds Need a Second Step**
> 
> A successful refund request creates a claim, not an immediate transfer. Network fees and exchange rates can change the crypto amount. Verify existing claims before retrying a timed-out request.

> **Confirm Before Delivering or Charging Again**
> 
> Insufficient payment remains unpaid; excess payment does not create extra WISECP credit. Compare the provider's paid amount and status. Fast confirmation settings carry additional payment risk.

## Required Privileges

WISECP requires **Modules → Payment Gateways** (`MODULES_PAYMENT_SETTINGS`) for settings and **Billing → Edit** (`INVOICES_OPERATION`) for refunds.

The current API requires `btcpay.store.cancreateinvoice` and `btcpay.store.canviewinvoices`. Refunds require `btcpay.store.cancreatepullpayments`; finding existing claims requires `btcpay.store.canmanagepullpayments`. Restrict all four to the selected store. The operator also needs webhook management and payout approval/signing access; the module does not manage these automatically.

## Related Articles

- [Payment Modules](https://docs.wisecp.com/en/payment-modules)
- [Invoice Detail Overview](https://docs.wisecp.com/en/invoice-detail-overview)
- [BTCPay Server API and Permissions](https://docs.btcpayserver.org/API/Greenfield/v1/)
- [BTCPay Server Refunds](https://docs.btcpayserver.org/Refund/)