Monero Payment Gateway: Self-Hosted, Non-Custodial (MonkStash Pay)

A Monero payment gateway turns "pay with XMR" into something your shop can run on its own: an invoice per order, a checkout page for the customer, and a message to your shop when the money arrives. MonkStash Pay is a free gateway you host yourself. It holds no money and has no spend key, so the only person who can move your funds is you.

What a Monero payment gateway does

Whatever gateway you use, it has four jobs:

1. Make an invoice with a fresh address and an exact amount.
2. Show the customer how to pay: a QR code, the amount, a countdown.
3. Watch the blockchain for a payment to that address, which takes a view key.
4. Tell your shop when the order is paid, so it can ship.

The big question is where the view key lives. Hosted processors keep it (or your money) on their servers. MonkStash Pay keeps it on yours.

How MonkStash Pay works

1. Your shop asks for an invoice
   One API call: "€19.99, Order 1001".
2. MonkStash Pay creates it
   A fresh subaddress from your view-only wallet, the price converted to XMR and held for 30 minutes, and a checkout link.
3. The customer pays
   On the checkout page: QR code, exact amount, copy buttons and a status that updates by itself.
4. Your shop gets told
   A signed webhook for each change: confirming, paid, partly paid, late or expired.

Why it cannot lose your money

• View-only wallet. It is set up with your address and private view key only. Without the spend key, nothing on the server can send your XMR anywhere.
• No middleman. The customer pays your wallet directly. There is no balance on our side, because there is no our side.
• Locked-down checkout. Checkout pages use long random links, strict security headers and no third-party scripts, fonts or trackers.
• Careful defaults. The API needs a long secret key, requests are size- and rate-limited, and no customer data is written to logs.

The API in one minute

Create an invoice with one request. Keep the API key on your shop's server, never in a web page.

POST /api/invoices
Authorization: Bearer <your API key>
Content-Type: application/json

{ "amount": "19.99", "currency": "EUR", "reference": "Order 1001",
  "returnUrl": "https://yourshop.com/orders/1001" }

The reply includes the invoice id, the exact XMR amount, the held rate, the expiry time and a checkoutUrl to send your customer to. GET /api/invoices/:id returns the current status at any time:

Webhooks your shop can trust

Each status change is sent to your shop as a webhook, signed with HMAC-SHA256 and a timestamp. Your shop checks the signature before believing it, and rejects anything older than five minutes. If your shop does not answer, MonkStash Pay tries again after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours: six attempts in all, with the last one about eight and a half hours after the first.

For extra safety, our WooCommerce plugin goes one step further: after a valid webhook itasks the gateway for the real status before changing the order, so even a replayed or forged message cannot mark an order paid.

Monero payment gateways compared

BTCPay is a strong choice if you already run it. MonkStash Pay is for shops that want the same self-hosted privacy with less to install. Check each project's current documentation; these tools change.

What you need to run it

• A small server or VPS with Docker or Node.js 22 or newer, and HTTPS in front of it.
• A wallet for your shop, and its primary address, private view key and creation height. Never the seed or spend key.
• A Monero node you trust (your own is best).
• About 20 minutes, most of it waiting for the first sync.

Setup has three parts: fill in a settings file, build and run the server (with Docker or Node.js), and put it behind an HTTPS proxy such as Caddy or nginx. Test on stagenet, the free test network, before you take real money. The full guide, every setting and copy-paste webhook code for Node.js and PHP are in the project's README.

Status and limits

• One wallet and one shop per server.
• Invoices are kept in a single file: fine for thousands of orders, not millions.
• No admin screen yet; use the API or your shop's order list.

Selling in person instead? Use cashier mode. Invoicing a client? A payment link is all you need.