MakePay BTCPay Server Plugin

Overview

MakePay for BTCPay Server adds a native Other currencies payment method to BTCPay checkout. Merchants connect a MakePay company with OAuth, customers pay inside the BTCPay invoice checkout using any enabled MakePay-supported pay-in asset, and MakePay settles BTC on-chain to the BTCPay store wallet.

The plugin is designed for merchants who already use BTCPay Server invoices and want to keep BTCPay as the merchant checkout surface while adding MakePay's multi-chain pay-in experience.

Before you start

• BTCPay Server 2.3.5 or newer with plugin support enabled
• A BTCPay store with a BTC on-chain wallet configured
• Admin access to install server plugins and modify store wallet settings
• A public HTTPS BTCPay Server URL
• A MakeCrypto account with access to the MakePay company that should process payments
• MakePay payment settings configured for fees, refund handling, and allowed pay-in currencies

Version 1 settles to BTC on-chain only. Lightning settlement is not used by the BTCPay Server plugin.

Install the plugin

Install the latest package from the BTCPay Server Plugin Builder directory:

Open MakePay in BTCPay Plugin Builder

After the plugin is installed, restart BTCPay Server if the plugin manager asks for it. The store navigation then shows MakePay under wallets.

The public source repository is available here:

Open source repository

Connect MakePay

Open Store > Wallets > MakePay in BTCPay Server and use Connect MakePay. The connection flow:

1. Creates a store-specific native OAuth installation.
2. Opens MakeCrypto and asks you to sign in.
3. Lets you choose the MakeCrypto company to connect.
4. Shows the permissions requested by the BTCPay Server plugin.
5. Returns to BTCPay Server after approval.
6. Stores DPoP-bound OAuth tokens and a MakePay webhook signing secret in the BTCPay store settings.

The OAuth connection requests these scopes:

company:read
makepay:payment-links:read
makepay:payment-links:write
makepay:settings:read
makepay:settings:write

The plugin does not ask for wallet withdrawal permissions.

Configure settings

After connecting, review the General tab in BTCPay Server.

Setting	What it does
Enable MakePay	Turns the Other currencies checkout method on or off.
Ask customer for receipt email	When enabled, checkout asks the payer for a receipt email before payment.
Default receipt email	Used for MakePay receipts when customer email collection is disabled.
Refund address collection	Choose whether MakePay uses saved merchant refund wallets or asks the payer for a refund address when the selected pay-in chain needs one.

Use the Allowed currencies tab to control which MakePay pay-in assets appear inside BTCPay checkout. Leave every currency enabled to expose all supported MakePay assets, or disable currencies that should not be offered for this BTCPay store.

If Refund address collection is set to Merchant wallets, make sure the MakePay company has saved refund wallets for the chains you allow. If a chain does not have a merchant refund wallet, either add one in MakeCrypto or switch the BTCPay plugin setting to ask the payer.

Checkout flow

When a BTCPay invoice is created, the plugin prepares a MakePay payment link for that invoice:

1. BTCPay calculates the invoice amount and BTC amount due.
2. The plugin reserves a fresh BTC on-chain receive address from the BTCPay store wallet.
3. The plugin creates a MakePay payment link with source=btcpay-server, BTCPay store and invoice metadata, and a BTC settlement override pointing to that fresh receive address.
4. BTCPay checkout shows Other currencies as a payment method next to the normal BTC payment method.
5. The customer chooses a MakePay-supported pay-in currency, gets a live quote, and pays from the displayed address or QR code.

The customer stays in the native BTCPay invoice checkout. The plugin uses MakePay public payment-link APIs for supported assets, quotes, payment start, payment address generation, QR rendering, status polling, and quote refresh.

Settlement and accounting

MakePay settles the payment to the BTC address reserved for the BTCPay invoice. The plugin records a BTCPay payment only after MakePay reports the session as complete.

MakePay state	BTCPay behavior
complete	Record the settled MakePay payment and let BTCPay mark the invoice paid.
failed, expired, cancelled	Show the state without recording a settled payment.
underpaid	Keep the prompt non-settled so the invoice can be handled by policy or support.
Complete overpayment	Record the settled payment and preserve overpayment details in payment metadata.

Because the settlement destination is a BTCPay BTC address, BTCPay may also see the on-chain BTC settlement transaction. The plugin stores MakePay payment data on the MakePay prompt so settlement can be reconciled without duplicating payment records.

Webhooks and reconciliation

MakePay sends webhooks to the BTCPay plugin endpoint for the connected store. The plugin verifies x-makepay-signature with the stored MakePay webhook secret, checks timestamp freshness, and deduplicates delivery IDs before it updates a BTCPay invoice.

A background listener also reconciles pending MakePay prompts after BTCPay Server restarts or webhook delivery is missed.

Troubleshooting

If Other currencies is not shown on the invoice checkout, confirm the store has MakePay enabled, the OAuth connection is active, and the BTCPay store has a BTC on-chain wallet enabled.

If the OAuth approval returns an error, disconnect and connect again from the BTCPay MakePay settings page. Make sure the BTCPay Server URL is public HTTPS and that the browser is not opening an old OAuth approval tab from a previous connection attempt.

If checkout asks for a refund address even though you selected merchant wallets, open MakeCrypto payment settings and confirm that a merchant refund wallet is saved for the selected pay-in chain.

If a currency is missing in checkout, open the Allowed currencies tab in BTCPay and confirm that the asset is enabled. Also confirm the asset is currently supported by MakePay for payment links.

If an invoice does not become paid after the customer sends funds, open the MakeCrypto payment details page and check the timeline, selected pay-in asset, quoted amount, deposit address, and webhook requests. Then check BTCPay Server logs for MakePay webhook signature, invoice matching, or wallet-address errors.