How to Add Bitcoin Rewards to BTCPay Server with Oshi

BTCPay Server gives you full control over how you accept Bitcoin. Self-hosted, private, and built the way you want. Now you can add rewards on top of that.

By connecting BTCPay Server to Oshi, every eligible purchase can automatically earn Bitcoin (sats), turning your checkout into a simple, built-in loyalty experience — without changing your payment flow.

Let’s get started.

Step 1: Get Your BTCPay Server API Key

To connect BTCPay Server to Oshi, you’ll first generate an API Key inside BTCPay Server. This allows Oshi to securely listen for checkout events and issue rewards for eligible transactions.

🔑 Generate Your API Key

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

BTCPay will display your new API Key. Copy it before closing the window. You'll need it for the next step.

Step 2: Connect BTCPay Server in Oshi

Now that you have your API key, you’ll add BTCPay Server as a connection inside Oshi. These credentials securely link your BTCPay instance to your Oshi account.

🔌 Connect to Oshi

1. Log into the Oshi Dashboard
2. Go to Connections on the left sidebar
3. Find BTCPay Server and click Connect
4. Enter your BTCPay Server URL (this is the domain where your BTCPay Server is hosted)
5. Paste your API Key

Oshi will verify your credentials.

Once verified, Oshi will display a list of all stores available on your BTCPay Server account.

Step 3: Choose Which Store(s) to Connect

After authentication succeeds, you’ll choose which store Oshi should listen to.

Select the store(s) where you want customers to earn rewards, then click Connect.

Once you hit Connect, your BTCPay Server store is securely connected to Oshi. From now on, every eligible purchase through your store will automatically reward your customers with Bitcoin (sats).

Step 4: Choose How to Give Rewards

You can choose whether to give Bitcoin rewards on all BTCPay orders or only when the customer opts-in to marketing and offers.

Option 1: Rewards on All BTCPay Orders (Default)

This is the simplest and most common setup. Every completed BTCPay order automatically earns Bitcoin rewards.

• No extra configuration
• No custom code
• Works immediately after connecting

Choose this if you want a straightforward loyalty experience.

Option 2: Reward Only When Customers Opt-In

If you only want to reward customers who agree to receive marketing emails and special offers, you can require an opt-in.

In this mode:

• Customers earn sats only when they check the opt-in box
• If they don’t opt-in, the order will not generate rewards

This is useful when:

• You want rewards to function as an incentive to grow your email list
• You want more qualified marketing subscribers
• You want clearer consent before communicating with customers

In the next section, we’ll show you exactly:

• what the code snippet looks like
• where to paste it
• how Oshi detects whether a customer opted-in

How to set it up:

Oshi automatically looks for an opt-in flag in your BTCPay invoice metadata. If the flag is present, Oshi follows it. If it isn’t, rewards are issued to everyone by default.

To enable opt-in rewards, you need to do two things:

• Add a checkbox to your checkout form
• Pass the value to BTCPay when creating the invoice

✅ Add the Opt-In Checkbox

Add this to your checkout form (wherever you collect customer email):

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

Then include the value in your BTCPay invoice metadata:

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

How Oshi interprets it:

• buyerAcceptsMarketing: true → customer opted in → rewards issued
• buyerAcceptsMarketing: false → customer did not opt in → no rewards issued
• metadata missing entirely → rewards issued to everyone (default)

Referrals & Affiliates + BTCPay Checkouts

Oshi’s referral and affiliate programs let you pay referrals and commissions directly in Bitcoin. All referral and affiliate links redirect customers to the business website URL you set in your Oshi dashboard.

If your checkout eventually routes customers into BTCPay Server, you’ll need to make sure referral tracking makes it all the way through to the invoice.

That means your site must:

• Capture the UTM parameters from the referral link (e.g., ?utm_source=abc123, ?ref=abc123) when the customer lands
• Store them via cookies or local storage
• Include the referral and UTM values in the BTCPay invoice metadata

"metadata": {
  "email": "customer@example.com",
  "ref": "pvHefU",
  "utm_source": "oshi",
  "buyerAcceptsMarketing": true
}

This ensures that when a referred customer completes payment in BTCPay Server, the referral is tracked correctly and commissions are issued in Bitcoin. 

If you’re not sure how to implement this, your web developer can set it up quickly using standard tracking methods.

What’s Next?

Now that your BTCPay Server store is connected, it’s time to configure your rewards inside the Oshi Dashboard. This is where you’ll set up and manage everything your customers will see.

In your Oshi Dashboard, you can:

• Set up Bitcoin rewards for every purchase.
• Create VIP tiers for your top customers.
• Launch referral programs that incentivize word-of-mouth.
• Enable social engagement rewards for follows on X, Instagram, TikTok, and more.

You’ve done the hard part — now it’s time to turn every purchase into a reason for customers to come back.

Ready to boost engagement and stand out from the competition?

Head back to your Oshi Dashboard and launch your Bitcoin rewards program today.

Why It Works

Traditional rewards programs help retain existing customers—but they don’t attract new ones. Bitcoin fixes that.

With Oshi, you’re tapping into a growing audience of Bitcoiners who actively seek out places to earn sats. You’re not just giving rewards. You’re giving them a reason to walk in the door.

About BTCPay Server

BTCPay Server is an open-source Bitcoin payment processor that lets businesses accept payments directly without intermediaries, custodians, or added processing fees. You host it yourself, control your data, and decide exactly how checkout works. When connected to Oshi, every eligible purchase can automatically earn Bitcoin (sats), adding a powerful loyalty layer on top of your existing BTCPay checkout — without changing how you already take payments.