Financial Architecture

Technical specification of XMRShip's non-custodial Monero settlement pipeline, commercial carrier liquidity isolation, concurrency-safe balance ledger, and void refund accounting.

Monero

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/CAD and USD/CAD exchange 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 All or 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.

Need a custom bulk balance top-up or void refund?

Compare worked rate examples on Pricing or reach our treasury support team via Contact.