> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hiveinspect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Inspection Payments in the API: Invoices, Payer Shares and Refunds

> Read an inspection's invoice, payer shares, payments with Stripe ids, and refunds with the Hive Inspect API. Learn how to tell when an inspection has fully settled.

In the dashboard: open an inspection to see its payments, payer shares and refunds

> [!NOTE]
>
> **The Hive Inspect API is a work in progress.** It is available to a small group of accounts today, and the release for everyone is coming very soon. To ask for early access, message us from the chat bubble in your dashboard.

One request returns the full payment picture of an inspection: the invoice, what each payer owes, every payment with its Stripe id, every refund, and bank payments the bank rejected. It is read-only. The API cannot take, record or refund a payment.

```bash theme={"theme":{"light":"github-light","dark":"vesper"}}
curl "https://api.hiveinspect.com/v1/inspections/INSPECTION_ID/payments" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## What you get back

| Part | What it holds |
| - | - |
| Summary | `payment_status`, `paid`, `settled`, `has_refunds`, `currency`, and the `total`, `amount_paid` and `amount_due` across every payer |
| `invoice` | The invoice `id`, the order number (`order_id`) and the `invoice_number` |
| `shares` | One row per payer: who they are, what they owe, what they have paid, and a status |
| `payments` | Every payment: amount, method, whether it has settled, and the Stripe payment id |
| `refunds` | Every refund: amount, status, and the Stripe refund id |
| `failed_bank_payments` | Bank payments the bank rejected |

Amounts are in dollars in your account's currency, the same as the rest of the API.

## Check that an inspection is fully paid

Use `settled`. It is `true` only when all three are true:

* The inspection's `payment_status` is `paid`.
* Nothing is owed (`amount_due` is 0).
* No payment is still `processing`, `awaiting_closing` or `unknown`.

> [!WARNING]
>
> **`paid` is not the same as `settled`.** A bank payment (ACH) takes a few business days to clear. Unless your company turned on **Mark payment as paid only when ACH settles**, Hive shows the inspection as paid as soon as the client submits the bank payment. `settled` waits for the bank.

## Payment status

Each payment has a `status`:

| Status | Meaning |
| - | - |
| `settled` | The money has arrived. |
| `processing` | A bank payment that has not cleared yet. |
| `awaiting_closing` | Pay at close: the inspection is marked paid, but the money has not been collected or funded yet. |
| `unknown` | Stripe could not confirm the payment either way. Ask again later. |

For a bank payment made in the last 14 days, Hive asks Stripe for the real state when you make the request.

## Payer shares

`shares` shows who pays what. The main client's row has the id `primary`. Every other row is a share of the bill you sent to someone else, such as an agent, and has its own id.

Each share has a `status`: `pending`, `partial`, `processing` or `paid`.

> [!NOTE]
>
> **The summary is the truth for what is owed.** A share can stay open after someone else has paid the bill. For example, you send a share to an agent and the client then pays everything. The inspection is paid and `amount_due` is 0, while that share still shows `pending`. Do not add up the shares yourself.

## Amounts and the technology fee

Each payment has two amounts:

* **`amount`** is what was charged. On a card payment it includes the technology fee, unless your company absorbs it. This is the number to match against Stripe.
* **`services_amount`** is the part that paid for your services.

The summary and the shares use services amounts, without the fee.

## Stripe ids

* **`stripe_payment_intent_id`** (`pi_...`) is the payment on your own Stripe account.
* **`stripe_refund_id`** (`re_...`) is the refund on your own Stripe account.

Both are empty for payments and refunds made outside Stripe, such as cash, check or Zelle.

## Refunds and reversals

* **A refund** appears in `refunds` with a `status` of `pending`, `succeeded`, `failed` or `canceled`. A failed or canceled refund returned no money and is not counted.
* **A rejected bank payment** appears in `failed_bank_payments`. Hive removes it from `payments` and the inspection goes back to unpaid.
* **To find out when it happens**, subscribe to the `inspection.payment_updated` [webhook](https://docs.hiveinspect.com/api/webhook-events.md). It is sent for every payment, refund and rejected bank payment, and again when a bank payment settles. The message carries these same payment details.

## Things to know

* **Payment ids can change after an edit.** A payment keeps its `id`, unless someone uses **Edit Payment** or **Clear Payment** on the inspection. Those replace the payment records.
* **A share's charged amount is worked out.** Hive stores the services amount of a share payment. Its `amount` adds the technology fee and can differ from Stripe by a cent.
* **Refunds of a share's payment are not listed.** If you refund a payment made by another payer, it does not appear here yet.
* **Old payments can be missing details.** A few payments from before 2026 have no `id` or no card details.
* **Disputes are not included.** Chargebacks are not tracked in Hive. Check them in Stripe.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.