---
title: "Look up a bill"
method: POST
path: "/bill-payments/lookup"
tags: ["Bill Payments"]
---

# Look up a bill

`POST /bill-payments/lookup`

## Request

- The document declares no server URL.
- Auth: none declared. Required headers: `ApiKey`, `MerchantId`, `Environment`

Retrieves the bill a customer reference points to at a biller, and checks the amount to pay against it.

## Headers

- `ApiKey` string, required
- `MerchantId` string, required
- `Environment` 'live' | 'sandbox', required

## Request body

- LookupBillDto
  - `billerId` string, required: Identifier of the biller to look up
  - `reference` string, required: Customer reference for the bill, validated against the biller reference_rule
  - `amount` number: Amount to simulate fees for, when the biller allows partial payment. Defaults to the full bill amount.

## Response `200`

- BillDetailDto
  - `reference` string, required
  - `amount` number, required: Bill amount, excluding fees
  - `niirpayFees` number, required: NIIRPAY fees for this bill
  - `hub2Margin` number, required: HUB2 margin on top of NIIRPAY fees, capped by max_applicable_fees. Always 0 until HUB2C-3097 ships.
  - `totalAmount` number, required: Total amount due: bill + NIIRPAY fees + HUB2 margin
  - `currency` number, required: ISO 4217 numeric currency code
  - `invoices` BillInvoiceDto[]: Invoices to pay, in order, for CONTRACT billers
    - `reference` string, required
    - `amount` number, required
    - `invoice_display_order` number, required
    - `invoice_payment_order` number, required

## Other responses

- `400`: Bad Request
- `401`: Wrong credentials
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: ThrottlerException: Too Many Requests
- `500`: Internal error
- `502`: Invalid gateway

## Changes

- **2026-11-03** `f6d3f87df5e0`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/hub2/apis/hub2-service-api/changes/bill-payments/lookup/post.md)

---

[API](https://skmtc.dev/hub2/apis/hub2-service-api.md) - [All operations](https://skmtc.dev/hub2/apis/hub2-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/hub2/apis/hub2-service-api/revisions/f6d3f87df5e0?raw)