> ## 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. # List boletos > Lists boletos with optional status, kind, type, batch and date filters, paginated. Kind BATCH lists the items of batches, and batchId the items of one batch. ## OpenAPI ````yaml /pt/openapi/v3-current/payments.yaml get /v1/boletos 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/boletos: get: tags: - Boletos summary: List boletos description: >- Lists boletos with optional status, kind, type, batch and date filters, paginated. Kind BATCH lists the items of batches, and batchId the items of one batch. operationId: listBoletos parameters: - description: >- Midaz organization whose boletos are listed. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only boletos of this organization are listed and counted. in: header name: X-Organization-Id schema: description: >- Midaz organization whose boletos are listed. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only boletos of this organization are listed and counted. type: string - description: Status filter. explode: false in: query name: status schema: description: Status filter. enum: - PENDING - CREATED - SETTLED - CANCELED - INACTIVATED - FAILED examples: - CREATED type: string - description: Boleto kind filter. BATCH lists the items of batches. explode: false in: query name: kind schema: description: Boleto kind filter. BATCH lists the items of batches. enum: - SINGLE - INSTALLMENT - BATCH examples: - SINGLE type: string - description: Boleto type filter. explode: false in: query name: type schema: description: Boleto type filter. enum: - TRADITIONAL - QR_CODE - HYBRID examples: - TRADITIONAL type: string - description: >- Batch filter: only the boletos created as items of this batch. A value that is not a UUID is refused with 400 PBP-0001. A batch that does not exist, or that belongs to another organization, yields an empty list (total 0), not 404: this is a filter. Combined with a kind other than BATCH, the list is empty. explode: false in: query name: batchId schema: description: >- Batch filter: only the boletos created as items of this batch. A value that is not a UUID is refused with 400 PBP-0001. A batch that does not exist, or that belongs to another organization, yields an empty list (total 0), not 404: this is a filter. Combined with a kind other than BATCH, the list is empty. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string - description: >- Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). explode: false in: query name: from schema: description: >- Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). examples: - '2026-01-01' pattern: >- ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$ patternDescription: a YYYY-MM-DD date or an RFC 3339 date-time with offset type: string - description: >- Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). explode: false in: query name: to schema: description: >- Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B). examples: - '2026-12-31' pattern: >- ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$ patternDescription: a YYYY-MM-DD date or an RFC 3339 date-time with offset type: string - description: Due-date lower bound, inclusive. explode: false in: query name: dueDateFrom schema: description: Due-date lower bound, inclusive. examples: - '2026-02-01' format: date type: string - description: Due-date upper bound, inclusive. explode: false in: query name: dueDateTo schema: description: Due-date upper bound, inclusive. examples: - '2026-11-30' format: date type: string - description: Page number, one-based. explode: false in: query name: page schema: default: 1 description: Page number, one-based. examples: - 1 format: int64 minimum: 1 type: integer - description: Items per page. explode: false in: query name: limit schema: default: 20 description: Items per page. examples: - 20 format: int64 maximum: 100 minimum: 1 type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/ListBoletosResponse' description: OK '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Bad Request '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. '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Service Unavailable. 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. security: - BearerAuth: [] components: schemas: ListBoletosResponse: additionalProperties: false properties: items: items: $ref: '#/components/schemas/GetBoletoResponse' type: - array - 'null' limit: format: int64 type: integer page: format: int64 type: integer total: format: int64 type: integer required: - items - page - limit - total 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 GetBoletoResponse: additionalProperties: false properties: amount: type: string barcode: type: string batchId: description: >- Batch the boleto was created in, as one of its items. Present only on a boleto of kind BATCH, absent on every other kind. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string batchPosition: description: >- Position of the boleto in its batch, zero-based: the position of its item in the batch request. Present only on a boleto of kind BATCH, absent on every other kind. examples: - 3 format: int64 maximum: 24 minimum: 0 type: integer cancelable: description: >- Whether cancelling this boleto would effect a cancellation at the provider. Always present. Derived from the boleto's state, not from any request field: true only for a CREATED boleto that carries a providerId. An already-canceled boleto reads false even though POST /v1/boletos/{id}/cancel answers it 200 as an idempotent replay. type: boolean canceledAt: type: string cancellationReason: type: string createdAt: type: string digitableLine: type: string discount: $ref: '#/components/schemas/DiscountResponse' dueDate: type: string errorMessage: type: string excessPayments: description: >- Payments a SETTLED hybrid boleto received after it was settled, by the leg that did not settle it, when the provider attaches them to the boleto. A payment by that leg that the provider does not attach to the boleto reaches the collection account without being listed here. They are never credited: the boleto stays settled by the leg in paidVia. At most one is recorded per leg: a later payment by a leg already listed is not added. Only a hybrid boleto carries them, and the member is absent when there is none. items: $ref: '#/components/schemas/ExcessPaymentResponse' maxItems: 10 type: array failedAt: type: string fine: $ref: '#/components/schemas/FineResponse' guarantor: $ref: '#/components/schemas/GuarantorResponse' description: >- Final beneficiary (sacador avalista) of the boleto: the holder of the issuing account, read from that account's registration data at issuance. It is a snapshot: a later change to the registration does not change it. Absent on boletos issued before the final beneficiary was derived. id: type: string inactivatedAt: type: string installmentLabel: type: string instructions: type: string interest: $ref: '#/components/schemas/InterestResponse' kind: description: >- Issuance form of the boleto: SINGLE for a standalone boleto, INSTALLMENT for an installment of a series, BATCH for an item of a batch, which carries batchId and batchPosition. type: string ledgerId: description: Midaz ledger the boleto was written with. Always present. type: string midazAccountId: description: >- Midaz account the boleto was issued for: the midazAccountId it was created with. The settlement credit of a settled boleto is posted to this account. Always present. type: string midazOperationId: type: string organizationId: description: >- Midaz organization the boleto was written with. Always present, and always the organization of the X-Organization-Id header. type: string ourNumber: description: >- Bank-side identification of the boleto (nosso numero), as assigned by the provider and printed on the instrument. Read from the barcode and returned in the instrument's form, with leading zeros: the width is set by the connected provider (11 digits for the current one). When the payee supplied ourNumber on issuance, this field still reports the instrument and not the value supplied: if the two differ, the value here is the one printed on the boleto, and the divergence is recorded by the service. Optional: absent for boletos issued before this field existed, and absent while the provider has not produced a valid barcode. Absence means not yet known; the periodic reconciliation fills it in once the provider produces the instrument, with no action needed from the client; it is never sent as an empty string. examples: - '00000000029' type: string ourNumberDigit: description: >- Check digit of ourNumber, computed by the bank and never accepted in a request. Optional: absent whenever the provider did not return it, in which case ourNumber is presented alone, with no trailing hyphen. It is absent in particular when the payee supplied ourNumber: the current provider returns the digit only for numbers it assigned itself. When present, the canonical presentation is {ourNumber}-{ourNumberDigit}. examples: - '3' type: string paidVia: description: >- Leg by which the boleto was paid: BOLETO for a payment of its barcode or digitable line, PIX for a payment of a hybrid boleto's Pix QR code. Present only on a SETTLED boleto, absent on every other status. A traditional boleto is always paid by BOLETO. Set once, when the boleto settles: a later payment by the other leg does not change it and, when the provider attaches it to the boleto, is listed in excessPayments. enum: - BOLETO - PIX type: string payer: $ref: '#/components/schemas/PayerResponse' pixLocation: description: >- Location of the hybrid boleto's dynamic Pix QR code, as issued. For support and diagnostics: to pay, the payer uses qrCode. Only a HYBRID boleto carries it, and it is served together with qrCode, under the same rule: absent while the boleto is PENDING or FAILED, present once it is CREATED and on every later status; absent on every other type. examples: - pix.example.com/qr/v2/cobv/5d9a8e91c88c43db942d01a0ad92ffc3 type: string pixTxId: description: >- Identifier of the due-date Pix charge attached to a hybrid boleto. Only a HYBRID boleto carries it, and only once its issuance is confirmed; absent on every other type. examples: - 35dabf21d3b941e8a937409b8749f281 type: string providerId: description: >- Identifier the payment provider assigned to this boleto. Quote it when you contact the provider about this boleto. type: string qrCode: description: >- Pix copy-and-paste code of a HYBRID boleto's Pix charge: the payload behind its QR code, which the payer scans or pastes to pay by Pix. Served only after the provider has registered the boleto, so it is never paid into a boleto whose registration fails: absent while the boleto is PENDING or FAILED, and so from the 201 and the 202 of its creation, which answer it PENDING; present on the read once the boleto is CREATED, and on every later status. Absent on a type without a Pix charge. type: string seriesId: type: string settledAmount: type: string settledAt: type: string status: type: string type: type: string updatedAt: type: string required: - id - organizationId - ledgerId - midazAccountId - type - kind - status - cancelable - amount - dueDate - payer - createdAt - updatedAt type: object 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 DiscountResponse: additionalProperties: false properties: amount: type: string limitDate: type: string type: type: string required: - type - amount - limitDate type: object ExcessPaymentResponse: additionalProperties: false properties: amount: description: Amount received, as a decimal string with two decimal places. examples: - '10.00' type: string detectedAt: description: When the service recorded this payment as an excess payment. format: date-time type: string paidAt: description: >- When the payer made this payment, as the payment provider reports it. When the provider reports no instant, it is the moment the service observed the payment. format: date-time type: string paidVia: description: >- Leg this payment arrived by: always the leg that did not settle the boleto. enum: - BOLETO - PIX type: string providerReference: description: >- Reference of this payment at the payment provider: the end-to-end identifier of a Pix payment, or the authorization identifier of a boleto payment. Absent when the provider sent none. type: string required: - paidVia - amount - paidAt - detectedAt type: object FineResponse: additionalProperties: false properties: amount: type: string type: type: string required: - type - amount type: object GuarantorResponse: additionalProperties: false properties: address: $ref: '#/components/schemas/AddressResponse' description: >- Never filled for the final beneficiary: the issuing account's registration data carries no address for it. Kept so the shape of this component does not change. document: description: >- CPF or CNPJ of the final beneficiary, the issuing account's holder, as registered. Answered whole, never masked, wherever this component appears. type: string name: description: >- Name of the final beneficiary, the issuing account's holder, as registered and in full. The printed boleto may abbreviate it; this member never does. type: string required: - name - document type: object InterestResponse: additionalProperties: false properties: amount: type: string type: type: string required: - type - amount type: object PayerResponse: additionalProperties: false properties: address: $ref: '#/components/schemas/AddressResponse' document: type: string name: type: string required: - name - document type: object AddressResponse: additionalProperties: false properties: city: type: string complement: type: string neighborhood: type: string number: type: string state: type: string street: type: string zipCode: 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.