How to Connect BTCPay Server

Connecting BTCPay Server to Oshi lets you add Bitcoin rewards to your existing BTCPay checkout. Your payment flow stays the same — Oshi listens for completed purchases and issues rewards automatically.

Steps

Step 1: Generate a BTCPay Server API Key

1. Log into your BTCPay Server
2. Navigate to Account > Manage Account > API Keys
3. Click Generate Key
4. Select these permissions:
   • View invoices
   • View stores
   • Modify stores webhooks
5. Click Generate API Key

Copy the key before closing the window — you'll need it in the next step.

Step 2: Connect BTCPay Server in Oshi

1. From your Oshi dashboard, go to Connections in the left sidebar
2. Find BTCPay Server and click Connect
3. Enter your BTCPay Server URL (the domain where your BTCPay instance is hosted)
4. Paste your API Key

Oshi will verify your credentials and display a list of stores on your BTCPay account.

Step 3: Select Your Store

Choose which store(s) you want Oshi to listen to for purchases. Click Connect to finalize.

Step 4: Choose How to Give Rewards

You have two options:

Option 1: Rewards on all orders (default) — Every completed BTCPay order automatically earns Bitcoin rewards. No extra configuration needed.

Option 2: Rewards only when customers opt in — Only reward customers who explicitly agree to receive marketing emails. This is useful if you want rewards to function as an incentive to grow your email list, or you want clearer consent before communicating with customers.

If you choose Option 2, you'll need to add an opt-in checkbox to your checkout and pass the value to Oshi through the invoice metadata. See the implementation details below.

Implementing the Opt-In Checkbox

Since BTCPay Server is self-hosted, adding the opt-in requires a small code change to your checkout template.

Add the Checkbox to Your Checkout Form

Add this wherever you collect the customer's email:

<label>
  <input type="checkbox" name="buyerAcceptsMarketing">
  Earn Bitcoin rewards and receive occasional offers by email
</label>

Pass the Value in Your Invoice Metadata

When creating the BTCPay invoice, include the checkbox value in the metadata:

{
  "metadata": {
    "email": "customer@example.com",
    "buyerAcceptsMarketing": true
  }
}

How Oshi Interprets It

• buyerAcceptsMarketing: true — Customer opted in, rewards are issued
• buyerAcceptsMarketing: false — Customer did not opt in, no rewards issued
• Metadata missing entirely — Rewards are issued to everyone (default behavior)

What's Next

• Set up referral and affiliate tracking — If you use Oshi's referral or affiliate programs, you'll need to pass referral parameters through to your BTCPay invoice metadata.
• Set up purchase rewards — Configure how much Bitcoin customers earn on each order.
• Fund your rewards balance — Make sure your account has enough sats to cover rewards.