Billing API

Read your monthly billing summary and outstanding invoices via the SDK.

HivePay charges merchants on a monthly cycle — see Billing & Pricing for the model. The SDK exposes one method merchants typically need: billing.getMine().

Get Your Billing Summary

Returns the current-month volume, the projected invoice at the prevailing tier, and the full history of outstanding and paid invoices.

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

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

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

use HivePay\HivePay;

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

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

curl https://hivepay.me/api/public/billing/me \
  -H "Authorization: Bearer sk_live_xxx"

Response Shape

Field	Type	Description
`merchantId`	`string`	Your merchant ID
`merchantName`	`string`	Your business name
`currentMonth.periodStart`	`Date` / ISO string	UTC start of the current month
`currentMonth.periodEnd`	`Date` / ISO string	UTC start of the next month (exclusive)
`currentMonth.totalVolumeCents`	`number`	Volume processed this month, in USD cents
`currentMonth.transactionCount`	`number`	Completed transactions this month
`currentMonth.projectedInvoiceCents`	`number`	Projected month-end invoice at the prevailing tier
`outstandingInvoices`	`BillingPeriod[]`	Unpaid invoices (`invoiced` or `overdue`)
`paidInvoices`	`BillingPeriod[]`	Historical paid invoices
`outstandingAmountCents`	`number`	Sum of unpaid invoice amounts
`totalPaidCents`	`number`	Sum of all paid invoice amounts to date
`feeTiers`	`FeeTier[]`	Active tier schedule (sorted ascending by `minVolumeCents`)

BillingPeriod

Field	Type	Description
`id`	`string`	Unique billing period ID
`periodStart`	`Date` / ISO	First day of the billed month (UTC)
`periodEnd`	`Date` / ISO	First day of the next month (exclusive)
`totalVolumeCents`	`number`	Volume during the period (USD cents)
`transactionCount`	`number`	Completed transactions during the period
`invoiceAmountCents`	`number`	Invoice amount (USD cents)
`status`	`'open' \\| 'invoiced' \\| 'paid' \\| 'overdue'`	Current status
`invoiceSessionId`	`string \\| null`	Backing payment session ID
`invoiceSlug`	`string \\| null`	Slug of the invoice session
`invoicePaymentUrl`	`string \\| null`	Hosted URL to pay the invoice (only while unpaid)

FeeTier

Field	Type	Description
`minVolumeCents`	`number`	Inclusive lower bound (USD cents)
`maxVolumeCents`	`number \\| null`	Inclusive upper bound, or `null` for the open-ended top tier
`percentFee`	`number`	Percentage rate for volume in this tier (e.g. `1.5` = 1.5%)

Pay an Outstanding Invoice

Outstanding invoices each include an invoicePaymentUrl — share or open it to pay in HBD via a regular HivePay checkout.

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

for (const invoice of summary.outstandingInvoices) {
  if (invoice.invoicePaymentUrl) {
    console.log(`Pay $${invoice.invoiceAmountCents / 100} at ${invoice.invoicePaymentUrl}`);
  }
}

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

foreach ($summary['outstandingInvoices'] as $invoice) {
    if ($invoice['invoicePaymentUrl']) {
        echo 'Pay $' . ($invoice['invoiceAmountCents'] / 100)
            . " at {$invoice['invoicePaymentUrl']}\n";
    }
}

Display the Active Tier Schedule

The schedule shipped with HivePay is configurable per deployment. Read summary.feeTiers rather than hard-coding rates so your app stays in sync if rates change.

const { feeTiers, currentMonth } = await hivepay.billing.getMine();

const sorted = [...feeTiers].sort((a, b) => a.minVolumeCents - b.minVolumeCents);
const currentTier = sorted.find(t =>
  currentMonth.totalVolumeCents >= t.minVolumeCents
  && (t.maxVolumeCents === null || currentMonth.totalVolumeCents <= t.maxVolumeCents)
);

if (currentTier) {
  console.log(`You are in the ${currentTier.percentFee}% tier this month.`);
}

Polling for Invoice Payment

After redirecting yourself to an invoicePaymentUrl, you can poll getMine() to confirm settlement — the period status flips from invoiced to paid as soon as the invoice transaction is confirmed on Hive.

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

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

async function waitForInvoicePaid (invoiceId: string, timeoutMs = 5 * 60 * 1000) {
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    const summary = await hivepay.billing.getMine();
    const paid = summary.paidInvoices.find(i => i.id === invoiceId);
    if (paid) return paid;

    await new Promise(r => setTimeout(r, 5000));
  }
  throw new Error('Invoice not paid within timeout');
}

Error Handling

billing.getMine() requires a valid merchant API key. Common errors:

`error.code`	When
`AUTHENTICATION_ERROR`	Missing or invalid API key
`NETWORK_ERROR`	Network failure or timeout
`SERVER_ERROR`	Backend error (5xx)

import { HivePay, isHivePayError } from '@hivepay/client';

try {
  const summary = await hivepay.billing.getMine();
  // ...
} catch (err) {
  if (isHivePayError(err) && err.isAuthError()) {
    console.error('Check your API key');
  } else {
    throw err;
  }
}