> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # Consult a bill by digitable line > Consults a bill by its digitable line without paying it: the source's own view of the amount, the dates and who receives the money. **Why POST for a read.** The digitable line identifies a payable bill and is sensitive, so it travels in the body instead of the URL, where proxies, logs and browser history would keep it. Nothing is created or changed: the request carries no Idempotency-Key and repeating it is safe. **Local validation first.** The line must be 47 digits for a bank slip or 48 digits starting with 8 for a utilities bill, digits only and never normalized: any other form is refused with 400 PBP-0001 before any check digit is computed. A line in the right form whose check digits do not match is refused with 422 PBP-0100. Neither reaches the source. **Segments differ.** Every member of the answer is always present; a member the segment does not report is null. A bank slip reports payability, the face value, fine, interest, discount, the due and limit dates, the beneficiary and the receiving bank. A utilities bill reports the assignor, its segment, the state, the payment window and a settlement date, which is not a due date. A bank slip the source does not know is 404 PBP-0110; a utilities line the source does not know is refused with 422 PBP-0111. **Permission.** The operation requires `payments/create`, the same permission as initiating a payment: consulting is the first step of paying. **Isolation.** The tenant and the provider credential come from the token, never from the request. The `X-Organization-Id` header is required and validated in form (a canonical UUID); it does not scope the consult, which reads no stored data of any organization. ## OpenAPI ````yaml /pt/openapi/v3-current/payments.yaml post /v1/payments/consult openapi: 3.1.0 info: description: >- API for the Lerian Payments interface via BTG. It covers boleto issuance, cancellation, and queries; bill payments (bankslip, utilities, and DARF) and queries; aggregated boleto and payment dashboards; provider connection and outbound webhook configuration; and the provider webhook receiver for settlement events. ERROR BODIES. A failed request arrives as an RFC 9457 problem document on application/problem+json. Branch on the code member. A license refusal carries an LCS code, listed in the License Manager error list. title: Payments — via BTG API version: 1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: [] tags: - description: >- Tenant-level setup: connecting the banking provider and configuring where status notifications are delivered. name: Admin - description: Issuing, querying and cancelling boletos, and retrieving the rendered PDF. name: Boletos - description: >- Aggregated counts, amounts and breakdowns over a period, for boletos and for payments. name: Dashboards - description: >- Paying bankslips, utility bills and DARF tax slips, and querying those payments. name: Payments - description: >- The webhook the payment provider posts settlement events to. Authenticated with a credential agreed with the provider, not with the platform identity used by the rest of this API. name: Settlement paths: /v1/payments/consult: post: tags: - Payments summary: Consult a bill by digitable line description: >- Consults a bill by its digitable line without paying it: the source's own view of the amount, the dates and who receives the money. **Why POST for a read.** The digitable line identifies a payable bill and is sensitive, so it travels in the body instead of the URL, where proxies, logs and browser history would keep it. Nothing is created or changed: the request carries no Idempotency-Key and repeating it is safe. **Local validation first.** The line must be 47 digits for a bank slip or 48 digits starting with 8 for a utilities bill, digits only and never normalized: any other form is refused with 400 PBP-0001 before any check digit is computed. A line in the right form whose check digits do not match is refused with 422 PBP-0100. Neither reaches the source. **Segments differ.** Every member of the answer is always present; a member the segment does not report is null. A bank slip reports payability, the face value, fine, interest, discount, the due and limit dates, the beneficiary and the receiving bank. A utilities bill reports the assignor, its segment, the state, the payment window and a settlement date, which is not a due date. A bank slip the source does not know is 404 PBP-0110; a utilities line the source does not know is refused with 422 PBP-0111. **Permission.** The operation requires `payments/create`, the same permission as initiating a payment: consulting is the first step of paying. **Isolation.** The tenant and the provider credential come from the token, never from the request. The `X-Organization-Id` header is required and validated in form (a canonical UUID); it does not scope the consult, which reads no stored data of any organization. operationId: consultBill parameters: - description: >- Midaz organization of the caller. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. The organization is validated and does not scope the consult: the tenant and the provider credential come from the token. in: header name: X-Organization-Id schema: description: >- Midaz organization of the caller. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. The organization is validated and does not scope the consult: the tenant and the provider credential come from the token. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/ConsultBillRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/ConsultBillResponse' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The request is structurally invalid. PBP-0001 covers every schema refusal: the line not 47 digits, nor 48 digits starting with 8 (a 44-digit barcode, a 47-digit line starting with 8, a letter, a space or a hyphen), an absent body, a body that is not JSON, and a member the operation does not accept. The refusal never echoes the line. PBP-0025 means the `X-Organization-Id` header was absent or not a canonical UUID. '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again. '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- PBP-0110: the source has no bank slip for this line. Bank slips only: a utilities line the source does not know is 422 PBP-0111. '413': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Request Entity Too Large '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The line is well formed and cannot be consulted. PBP-0100: its check digits do not match. PBP-0111: the source refused the line with a reason of its own, whose code travels in the `providerCode` extension member when the source named one; for a utilities bill this includes a line the source does not know. PBP-0017: the tenant has no connection to the payment provider. '429': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- PBP-0112: the consult rate limit for this caller was exceeded. The count is keyed by `(tenantId, sub)` of the validated token: one client never consumes another client's budget, and one operator never consumes another operator's budget within the same client. A token without `sub` is refused with 401 PBP-0003 and counts nothing; the count never falls back to the IP address. Every consult that passes authentication counts, including one the schema then refuses. Initial limit: 100 consults per 60 s per key. ⚠️ The counter lives in process, so the ceiling is per replica: with N replicas the effective ceiling is N × the limit. It is a barrier against enumeration, not a guaranteed global quota. Payments by the same client are not affected by this limit. headers: Retry-After: description: >- Seconds to wait before retrying: the time left in the limiter's window for this key, a whole number of at least 1. schema: minimum: 1 type: integer X-RateLimit-Limit: description: The limit of the current window for the `(tenantId, sub)` key. schema: minimum: 0 type: integer X-RateLimit-Remaining: description: Consults left in the current window. schema: minimum: 0 type: integer X-RateLimit-Reset: description: >- Seconds until the current window resets, a whole number of at least 1. schema: minimum: 1 type: integer '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '502': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- PBP-0113: the source answered the consult in a way that cannot be acted on. Retrying the same line is unlikely to help. '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- PBP-0114: the bill source is temporarily unavailable — it did not answer, the consult's protection against a failing source is open, payments to the provider are suspended, the provider is limiting requests, or the tenant's provider credential cannot be used. The request may be retried; when the answer carries `Retry-After`, wait that long first. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send it again. headers: Retry-After: description: >- Seconds to wait before retrying, a whole number of at least 1. Present when the provider limited the request or payments to it are suspended; absent when the source named no wait. schema: minimum: 1 type: integer security: - BearerAuth: [] components: schemas: ConsultBillRequest: additionalProperties: false properties: digitableLine: description: >- Digitable line, digits only: 47 for a bank slip, or 48 starting with 8 for a utilities bill. maxLength: 48 minLength: 47 pattern: ^(?:[0-79][0-9]{46}|8[0-9]{47})$ type: string required: - digitableLine type: object ConsultBillResponse: additionalProperties: false properties: amount: description: Consulted amount, two decimal places. type: string assignor: description: Utility company. Utilities only. type: - string - 'null' beneficiary: $ref: '#/components/schemas/ConsultBillBeneficiaryResponse' description: Who receives the money, with the document masked. discount: description: Discount granted. Bank slip only. type: - string - 'null' dueDate: description: Due date. Bank slip only. format: date type: - string - 'null' fine: description: Fine charged. Bank slip only. type: - string - 'null' interest: description: Interest charged. Bank slip only. type: - string - 'null' limitDate: description: Last date the slip is payable. Bank slip only. format: date type: - string - 'null' maxAmount: description: Highest payable amount, when the source reports a band. type: - string - 'null' minAmount: description: Lowest payable amount, when the source reports a band. type: - string - 'null' originalAmount: description: Face value of the slip. Bank slip only. type: - string - 'null' payable: description: >- Whether the source accepts the bill for payment, as it reported. Bank slip only. type: - boolean - 'null' paymentWindow: $ref: '#/components/schemas/ConsultBillPaymentWindowResponse' description: Time of day the bill can be paid. Utilities only. receiverBank: $ref: '#/components/schemas/ConsultBillReceiverBankResponse' description: Bank that receives the payment. Bank slip only. segment: description: FEBRABAN segment the line was consulted on. type: string settlementDate: description: >- Settlement date the source reported. Utilities only; it is not a due date. format: date type: - string - 'null' state: description: Federative unit of the utility. Utilities only. type: - string - 'null' utilitySegment: description: The source's own segment text. Utilities only. type: - string - 'null' required: - segment - payable - amount - originalAmount - minAmount - maxAmount - fine - interest - discount - dueDate - limitDate - beneficiary - receiverBank - assignor - utilitySegment - state - paymentWindow - settlementDate type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ConsultBillBeneficiaryResponse: additionalProperties: false properties: document: description: Beneficiary document, masked. type: string name: description: Beneficiary name. type: string personType: description: >- PF for a person, PJ for a company, null for anything else the source reported, including nothing. enum: - PF - PJ - null type: - string - 'null' required: - name - document - personType type: - object - 'null' ConsultBillPaymentWindowResponse: additionalProperties: false properties: end: description: Closing time of the window. type: string start: description: Opening time of the window. type: string required: - start - end type: - object - 'null' ConsultBillReceiverBankResponse: additionalProperties: false properties: code: description: Bank code, three digits. type: string ispb: description: Bank ISPB. type: string name: description: Bank name. type: string required: - name - ispb - code type: - object - 'null' ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.