BTCPay Server Module

13 views Markdown

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 AddressRequired; empty by default. Your server's base HTTPS address, such as https://btcpay.example.com, without /api/v1.
API KeyRequired; empty by default. A Greenfield key restricted to this store, with the permissions listed below.
Store IDRequired; empty by default. Copy the store identifier from its settings page/address. It must belong to the API key's scope.
Webhook SecretEmpty by default; configure it for signed notifications. Without it, signature checking is skipped, although the invoice is still fetched through the API.
Confirmation SpeedDefaults 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 MethodsOptional; empty offers the store's enabled methods. To restrict them, enter their exact IDs separated by commas, for example BTC-CHAIN, BTC-LN.
Return AutomaticallyOn 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. 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.

Was this helpful?

Thanks for your feedback!

Still Need Help?

Our support team is here around the clock for anything you can't find above.

Contact Us Open a Ticket

We use cookies to keep you signed in, remember your language and currency, and improve the site. Cookie Policy