Financial Architecture
Technical specification of XMRShip's non-custodial Monero settlement pipeline, commercial carrier liquidity isolation, concurrency-safe balance ledger, and void refund accounting.
Self-Hosted Node Settlement
Invoices are generated via our internal BTCPay Server Greenfield API backed by a dedicated monerod full node and Wallet RPC container. No third-party crypto payment processor ever touches your transaction.
Carrier Liquidity Isolation
XMRShip maintains pre-funded commercial CAD and USD treasury floats with ShipStation/ShipEngine carrier partners. Carrier APIs debit our corporate float upon label generation, keeping user payments completely air-gapped from carrier billing records.
Atomic Ledger & Slippage Guard
Account balance deductions use database row-level locking (lockForUpdate()) and idempotent state checks to prevent double charges, paired with live carrier price verification prior to label purchase.
Invoice Settlement & Label Purchasing Pipeline
How funds move from invoice creation through carrier API label fulfillment and exception handling.
| Stage | Shipment Status | Accounting & System Action |
|---|---|---|
| 1. Rate Commitment | pending_payment |
Base carrier estimate is recorded in CAD. For Monero checkouts, BTCPay creates a unique subaddress invoice with a locked Base × 1.05 CAD equivalent. |
| 2. Settlement Verification | paid |
HMAC-SHA256 signed BTCPay webhook (InvoiceSettled) or synchronous balance/Stripe capture records an immutable Payment row and dispatches ProcessShipmentJob. |
| 3. Live Price Coverage Check | processing |
The queue worker executes priceStillCovered() with forceRefresh = true to verify the carrier's live uncached rate has not spiked above the settled invoice amount. |
| 4. Carrier Label Fulfillment | shipped |
XMRShip's commercial carrier float is debited, the 4×6 thermal PDF label is stored locally, and the master carrier tracking number is assigned. |
| 5. Cancellation & Refund Credit | voided |
If an unused label is voided before carrier scan induction, the carrier credits XMRShip's float and the user's account balance or refund ledger is credited accordingly. |
Service Markup Allocation
Why Monero carries a 5% markup while Account Balance and Cards carry a 10% markup:
- Fiat Liquidity Float (~2.5%): Maintaining pre-funded CAD and USD balances across multiple commercial carrier accounts so labels generate without settlement delay.
-
FX & Volatility Buffer (~1.5%): Absorbing short-term
XMR/CADandUSD/CADexchange rate fluctuations during invoice confirmation windows. - Infrastructure & Gateway Overhead (1%–6%): Full Monero node hosting, Tor hidden service relays, and (for non-XMR checkouts) payment processor interchange and dispute reserves.
Pre-Funded Account Balance Mechanics
High-volume dispatchers can enable a prepaid CAD account balance on their profile to bypass per-shipment block confirmation wait times:
- Funding Channels: Top up your CAD balance in bulk by contacting support on Signal or PGP email for a custom Monero settlement invoice.
-
Batch Cart Settlement: Pay for up to 100 queued CSV shipments in a single click using
Pay Allor selected batch checkout. -
Failed Label Protection: Balance funds are only deducted when the invoice transitions to
paid; if an upstream carrier API rejects an address, you can retry or request an immediate balance credit.