> ## 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, 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 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. 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/json: schema: $ref: '#/components/schemas/ErrorResponse' application/problem+json: schema: $ref: '#/components/schemas/Detail' text/plain: schema: type: string description: >- Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is either `application/json` with error code `PBP-0003` or `application/problem+json` (RFC 9457); read the `Content-Type` to parse it. The `text/plain` media type listed for this status is not returned. Obtain a valid bearer token and send the request again. '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 allowed to perform this request. The error body is `application/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. The `text/plain` media type listed for this status is not returned. '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/json: schema: $ref: '#/components/schemas/ErrorResponse' 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. 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 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.