> ## 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 /en/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, installments, and queries; bill payments (bankslip, utilities, and DARF), cancellation, 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 in one of two shapes, and which one you get depends on where the service catches the failure. A failure that the request pipeline catches before the API layer sees it answers a flat JSON body on application/json; the idempotency check is the pipeline rule you meet most often. Authentication and authorization refusals follow the response contract documented by the operation. Everything the API layer catches answers an RFC 9457 problem document on application/problem+json. Read the media type to tell the two apart. The code member holds the same PBP-NNNN value in both, so branch on it. One pipeline refusal is not listed on the operations below: while a first request under the same idempotency key is still in flight, a retry is answered 409 with code PBP-0007 and the flat body. title: Payments — via BTG API version: 1.0.0 servers: - url: https://payments.sandbox.lerian.net 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, including installment series and 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 or cancelling 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. Declared optional on the schema so that refusal keeps its own code instead of the schema's PBP-0001. 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. Declared optional on the schema so that refusal keeps its own code instead of the schema's PBP-0001. 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/json: schema: $ref: '#/components/schemas/ErrorResponse' application/problem+json: schema: $ref: '#/components/schemas/Detail' text/plain: schema: type: string description: >- Authentication failed. Read the `Content-Type`: the authentication middleware answers `application/json` carrying error code `PBP-0003`, and the in-service identity gate further down the chain answers `application/problem+json` (RFC 9457). The content map also declares `text/plain`, which NOTHING in this service produces. Do not write a client branch for it. '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' application/problem+json: schema: $ref: '#/components/schemas/Detail' text/plain: schema: type: string description: >- The authenticated principal is not permitted to perform this action. Answered as `application/json` carrying error code `PBP-0004` — unlike the 401, this status has exactly one reachable shape and no `application/problem+json` entry. The content map also declares `text/plain`, which NOTHING in this service produces. Do not write a client branch for it. '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' application/json: schema: $ref: '#/components/schemas/PipelineError' 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. 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 ErrorResponse: additionalProperties: false properties: code: type: string details: additionalProperties: {} type: object message: type: string title: type: string required: - code - title - message type: object PipelineError: additionalProperties: false description: >- The flat error body. A failure caught before the API layer sees the request answers this shape on the application/json media type, instead of the RFC 9457 problem document. Read the media type to tell the two apart. The idempotency check is the rule that answers this way most often. properties: code: description: >- Stable, machine-readable error code, in the form PBP-NNNN. Branch on this value. It carries the same meaning as the code member of the problem document. examples: - PBP-0013 type: string details: additionalProperties: true description: Optional object carrying further facts about this occurrence. type: - object - 'null' message: description: A human-readable explanation specific to this occurrence. examples: - >- The request body does not match the original request for this idempotency key. type: string title: description: Short label for the condition. examples: - Idempotency Key Conflict type: string required: - code - title - message 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.