Docs
Powered by

Billing & Pricing

How HivePay charges merchants — monthly billing on processed volume, with a tiered rate schedule.

How It Works

HivePay uses a monthly SaaS billing model. Customer payments flow directly to your Hive account in a single transfer — HivePay does not deduct anything from individual transactions. At the end of each calendar month, HivePay generates a single invoice based on your total processed USD volume for that month.

Component Description
Payment Amount Full amount paid by customer is transferred to your Hive account at settlement
Monthly Invoice One invoice per merchant, per calendar month, in HBD
Settlement Pay the invoice via a regular HivePay checkout URL

Tiered Rate Schedule

The fee rate applied to your monthly volume depends on the active fee tier schedule. Each tier has a USD-cent volume range and a percentage rate. The top tier is open-ended (maxVolumeCents = null).

The default schedule shipped with HivePay:

Monthly Volume (USD) Fee Rate
$0 – $999.99 1.5%
$1,000 – $9,999.99 1.0%
$10,000+ 0.5%

The fee is calculated against your total processed volume for the month and issued as one invoice.

Reading Your Billing Status

Use GET /api/public/billing/me (or hivepay.billing.getMine() in the SDKs) to read your current billing status. The response includes:

Field Description
currentMonth.totalVolumeCents Volume processed so far this month, in USD cents
currentMonth.transactionCount Number of completed payments so far this month
currentMonth.projectedInvoiceCents Projected month-end invoice at the prevailing tier
outstandingInvoices[] Unpaid invoices, each with an invoicePaymentUrl for one-click checkout
paidInvoices[] Historical paid invoices
outstandingAmountCents Sum of unpaid invoice amounts
totalPaidCents Sum of all paid invoice amounts to date
feeTiers[] Active tier schedule with minVolumeCents, maxVolumeCents, percentFee 
import { HivePay } from '@hivepay/client';

const hivepay = new HivePay({ apiKey: process.env.HIVEPAY_API_KEY! });

const summary = await hivepay.billing.getMine();

console.log(`Volume this month: $${summary.currentMonth.totalVolumeCents / 100}`);
console.log(`Projected invoice: $${summary.currentMonth.projectedInvoiceCents / 100}`);

for (const invoice of summary.outstandingInvoices) {
  console.log(`Owed: $${invoice.invoiceAmountCents / 100} — pay at ${invoice.invoicePaymentUrl}`);
}
 
use HivePay\HivePay;

$hivepay = new HivePay(['apiKey' => getenv('HIVEPAY_API_KEY')]);

$summary = $hivepay->billing->getMine();

echo 'Volume this month: $' . ($summary['currentMonth']['totalVolumeCents'] / 100) . "\n";
echo 'Projected invoice: $' . ($summary['currentMonth']['projectedInvoiceCents'] / 100) . "\n";

foreach ($summary['outstandingInvoices'] as $invoice) {
    echo "Owed: \${$invoice['invoiceAmountCents']} — pay at {$invoice['invoicePaymentUrl']}\n";
}
 
curl https://hivepay.me/api/public/billing/me \
  -H "Authorization: Bearer sk_live_xxx"

Invoice Lifecycle

stateDiagram-v2
    [*] --> open: Volume accrues
    open --> invoiced: Month-end roll-up
    invoiced --> paid: Merchant pays via invoicePaymentUrl
    invoiced --> overdue: Past due
    overdue --> paid: Late payment received
    paid --> [*]
Status Meaning
open Period is the current month — still accruing volume
invoiced Invoice generated and awaiting payment
overdue Invoice has passed its due date (default 30 days)
paid Invoice paid in full

Outstanding invoices include an invoicePaymentUrl — a hosted HivePay checkout URL that pays the invoice in HBD. The same URL works for human merchants and for automated x402 settlements.

Reading Tier Information Programmatically

Always use the feeTiers field on the billing summary to display rates — it reflects the schedule active for your account at request time.

const summary = await hivepay.billing.getMine();

for (const tier of summary.feeTiers) {
  const upper = tier.maxVolumeCents === null
    ? 'unlimited'
    : `$${tier.maxVolumeCents / 100}`;
  console.log(`$${tier.minVolumeCents / 100} – ${upper}: ${tier.percentFee}%`);
}
 
$summary = $hivepay->billing->getMine();

foreach ($summary['feeTiers'] as $tier) {
    $upper = $tier['maxVolumeCents'] === null
        ? 'unlimited'
        : '$' . ($tier['maxVolumeCents'] / 100);
    echo '$' . ($tier['minVolumeCents'] / 100) . " – {$upper}: {$tier['percentFee']}%\n";
}

Format Satoshis

Customer-facing payment amounts are denominated in satoshi strings. Use formatSatoshis to render them as decimals — there is no separate "fee" amount to compute, since the full payment is transferred to the merchant.

import { formatSatoshis } from '@hivepay/client';

console.log(formatSatoshis('10500')); // "10.500"
console.log(formatSatoshis('150'));   // "0.150"
console.log(formatSatoshis('1'));     // "0.001"
 
use HivePay\Fee;

echo Fee::formatSatoshis('10500'); // "10.500"
echo Fee::formatSatoshis('150');   // "0.150"

HivePay © 2026