Get paid in Monero, non-custodially.

Getting started

Introduction

Umbra is a Monero payment gateway. You give it your wallet address and your private view key, never your spend key, and it mints a fresh subaddress for every invoice, watches the chain for payments to it, and calls your server when one arrives.

Because a view key can only read, funds land in your wallet and stay there. Umbra cannot spend them, freeze them, or hand them to anyone else.

• REST over HTTPS, JSON in and out. No SDK required.
• Prices in XMR, or in 12 fiat currencies with the rate locked at creation.
• Two webhook events: one at 0-conf, one at the confirmation threshold.
• A hosted checkout page with a QR code, or build your own from the API.

How it works

Quickstart

Four steps from nothing to a settled payment. Everything below works with curl.

1. Create your account

The API key and webhook secret come back once and are never shown again. Umbra stores only a hash of the key, so a lost key cannot be recovered.

curl -X POST https://www.umbra.international/api/merchants \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Shop",
    "address": "4...",              # your Monero address
    "view_key": "...",              # private VIEW key, 64 hex chars
    "webhook_url": "https://myshop.com/umbra/webhook"
  }'

# Response. api_key and webhook_secret are shown once, store them now.
{
  "merchant_id": "1cf6b8b8-...",
  "api_key": "xmr_sk_...",
  "webhook_secret": "..."
}

2. Create an invoice

Price in fiat with price_amount and price_currency, or in Monero with amount_xmr. Fiat prices are converted at creation and the rate is locked for the life of the invoice.

curl -X POST https://www.umbra.international/api/invoices \
  -H "Authorization: Bearer $UMBRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "price_amount": "25.00",
    "price_currency": "USD",
    "description": "Order #1042",
    "return_url": "https://myshop.com/orders/1042",
    "metadata": { "order_id": 1042 }
  }'

{
  "invoice_id": "0c0766e8-...",
  "subaddress": "8...",
  "amount_xmr": "0.044186005408",
  "price_amount": "25.00",
  "price_currency": "USD",
  "rate": 565.8,
  "status": "pending",
  "expires_at": "2026-09-22T11:54:03.184Z",
  "checkout_url": "https://www.umbra.international/checkout/0c0766e8-..."
}

3. Send the buyer to the checkout

Redirect them to checkout_url. The page shows the amount, a QR code and a monero: link, and updates itself as the payment lands. If you passed a return_url, they get a link back to your order page.

4. Settle on the webhook

Verify the signature, fulfil the order, and reply 200. Anything else is treated as a failure and retried.

import crypto from "crypto";

// rawBody must be the raw bytes, not parsed-and-restringified JSON.
const expected = crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

const got = req.headers["x-webhook-signature"] ?? "";
const ok =
  got.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));

if (!ok) return res.status(401).end();   // never parse an unverified body
// ... fulfil the order, then:
res.status(200).end();

Authentication

Every merchant endpoint takes your API key as a bearer token: Authorization: Bearer xmr_sk_…. Missing or unknown keys get 401.

Two routes are deliberately public, because the buyer needs them and has no key: GET /api/invoices/:idand the checkout page. The invoice id is the capability, so treat it as a secret URL and don't put it anywhere public.

Core concepts

Invoices

An invoice is one payment request: an amount, a subaddress, and a deadline.

Parameters

Amounts

Amounts are exact. Internally everything is integer piconero (10^-12 XMR), so nothing is lost to floating point. The API gives you both amount_atomic and a decimal amount_xmr string.

Payment statuses

A detected payment can still vanish: a dropped or replaced transaction, or a reorg. If that happens the invoice falls back to pending and its payment_detected webhook is withdrawn before delivery. This is why goods worth more than a coffee should ship on payment_confirmed.

Webhooks

Umbra POSTs JSON to the URL registered on your account, once per state change. The event name is in X-Webhook-Event and the signature in X-Webhook-Signature.

POST /umbra/webhook
X-Webhook-Event: payment_confirmed
X-Webhook-Signature: f889d2ae...ec23a      # HMAC-SHA256, hex, no prefix

{
  "event": "payment_confirmed",
  "invoice_id": "0c0766e8-...",
  "merchant_id": "1cf6b8b8-...",
  "amount_due_xmr": "0.044186005408",
  "amount_received_xmr": "0.044186005408",
  "price_amount": "25.00",
  "price_currency": "USD",
  "rate": "565.8",
  "txids": ["5faf1d15...99717"],
  "confirmations": 10,
  "metadata": { "order_id": 1042 },
  "timestamp": "2026-09-22T11:57:10.433Z"
}

Reply with any 2xx once you have stored the event. Umbra retries anything else, so a slow or failing endpoint will receive the same event again.

Verifying signatures

The signature is HMAC-SHA256 of the raw request body, hex-encoded, keyed with your webhook secret. There is no prefix and no timestamp in the value. Compare in constant time, and never parse a body you haven't verified.

import crypto from "crypto";

// rawBody must be the raw bytes, not parsed-and-restringified JSON.
const expected = crypto
  .createHmac("sha256", WEBHOOK_SECRET)
  .update(rawBody)
  .digest("hex");

const got = req.headers["x-webhook-signature"] ?? "";
const ok =
  got.length === expected.length &&
  crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));

if (!ok) return res.status(401).end();   // never parse an unverified body
// ... fulfil the order, then:
res.status(200).end();

Retries & redelivery

A delivery is attempted up to 8 times with exponential backoff, starting at 10 seconds and capping at an hour, with a 10-second timeout per attempt. Deliveries are queued per invoice and event, so an event is never duplicated by the queue itself, though a retry can still arrive after your handler succeeded, so make handlers idempotent.

You can inspect every attempt, including the last error, and push a delivery back onto the queue by hand.

API reference

Invoices

Account

Errors

Errors are JSON: { "error": "amount_xmr must be positive" }, with a status that says whose problem it is.

Integrations

Shopify

Buyers pick Pay with Monero at checkout, Shopify holds the order as pending, and Umbra marks it paid once the invoice confirms. Setup is six steps and no code.

curl -X PUT https://www.umbra.international/api/me/shopify \
  -H "Authorization: Bearer $UMBRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "shop_domain": "your-store.myshopify.com",
    "client_id": "<Client ID>",
    "client_secret": "<Client secret>"
  }'

{% if financial_status == "pending" %}
  <p>
    <a href="https://www.umbra.international/shopify/pay/your-store.myshopify.com/{{ id }}">
      Pay with Monero
    </a>
  </p>
{% endif %}

What happens to each order

WooCommerce

Install the plugin, paste in two keys, and Monero appears at your checkout. Works with the classic and the block checkout, and needs no build step.

curl -X POST https://www.umbra.international/api/me/webhook \
  -H "Authorization: Bearer $UMBRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"webhook_url": "https://yourstore.com/?wc-api=umbra_monero"}'

What happens to each order

Going live

Checklist

• Run your own Monero node. A public node can see which blocks you request. Your own node keeps that to yourself.
• Back up your master key. It encrypts stored view keys; lose it and they cannot be decrypted.
• Use the final HTTPS host everywhere. A redirect from the bare domain to www counts as a failed webhook delivery.
• Return 200 quickly and do slow work afterwards; the delivery times out after 10 seconds.
• Make handlers idempotent. A retry can arrive after you already fulfilled.
• Send one small real payment before launch, end to end.

Limits & currencies

Something missing or wrong here? Tell us. These docs describe a gateway that is still being built in the open.