> ## Documentation Index > Fetch the complete documentation index at: https://developers.portao3.com.br/llms.txt > Use this file to discover all available pages before exploring further. # List the realm's boleto payments > Lists the boleto payments of every organization in your realm, newest first. Filter by `status`, which takes its values comma-separated (`?status=PAID,FAILED`), and page with `limit` + `next`. Any other query parameter filters by the exact value of that field of the payment — for example `?organizationId=…` or `?type=UTILITY_BILL`. Payments of the other environment are not listed, so send `x-environment: LIVE` for production payments. A payment waiting for approval whose deadline passed is listed as `EXPIRED`. ## OpenAPI ````yaml /api-reference/banking.openapi.json get /realms/{realmId}/boleto openapi: 3.0.3 info: title: Banking version: 1.0.0 description: >- Portão 3 banking API. Every endpoint requires a bearer token in the Authorization header (Authorization: Bearer ) unless its page states otherwise; see the Authentication guide. That requirement is not repeated per endpoint. Generated by tools/openapi from code (routes + security) and the hand-written spec (request/response bodies). Banking attaches a zod validationSchema at the route; request bodies are resolved from it (object + array roots). Responses have no presenter layer, so they stay tier=unknown. Confidence tiers: generated:typed=262 copied:manual=1 unknown=35. servers: - url: https://api.banking.v2.portao3.com.br/ description: production - url: https://api.banking.dev.3pers.com.br/ description: development security: [] tags: - name: Accounts - name: Account Limits - name: Wallets - name: Transaction Limits - name: Transfers - name: Cards - name: Card Limits - name: Cards 3DS - name: Pix Payments - name: PIX Keys (DICT) - name: PIX Charges - name: PIX Automatic - name: PIX Initiation (Open Finance) - name: PIX Infractions (MED) - name: Boleto Payments - name: Boleto Charges - name: TED - name: Transactions - name: Cashback - name: Currency Codes - name: Reversals paths: /realms/{realmId}/boleto: get: tags: - Boleto Payments summary: List the realm's boleto payments description: >- Lists the boleto payments of every organization in your realm, newest first. operationId: getRealmsByRealmIdBoleto parameters: - name: realmId in: path required: true description: |- ID of your realm. Format: `UUID` schema: type: string format: uuid example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b - name: x-environment in: header required: false description: >- Environment whose payments you list: `LIVE` (production) or `TEST` (sandbox). When you omit it, you get the `TEST` payments; any other value is rejected. schema: type: string enum: - LIVE - TEST example: LIVE - name: status in: query required: false description: >- Only payments in these statuses (case-insensitive): `REQUESTED`, `PENDING_APPROVAL`, `EXPIRED`, `SCHEDULED`, `PAID`, `FAILED`, `CANCELLED` or `REFUNDED`. `PENDING_APPROVAL` leaves out payments whose approval deadline passed, which `EXPIRED` includes. Other values match no payment. --- Example (comma-separated list): `?status=PAID,FAILED` schema: type: array items: type: string maxLength: 64 style: form explode: false - name: next in: query required: false description: >- Cursor returned as `next` by the previous page. Omit it for the first page. schema: type: string example: NjcyNmIxYzJiNGQzZTgwMDEyYzlhNGEx - name: limit in: query required: false description: Page size. Defaults to 15. schema: type: integer minimum: 0 exclusiveMinimum: true example: 15 responses: '200': description: Successful response content: application/json: schema: type: object properties: items: type: array items: type: object properties: _id: type: string description: >- ID of the payment. Use it as `{boletoId}` in the payment endpoints. example: 6726b1c2b4d3e80012c9a4a1 environment: type: string enum: - LIVE - TEST description: >- Environment of the payment: `LIVE` (production) or `TEST` (sandbox). example: LIVE realmId: type: string description: ID of the realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organizationId: type: string description: ID of the organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid accountId: type: string description: ID of the organization's account. example: 66f2a1c7b4d3e80012c9a0b4 walletId: type: string description: ID of the wallet that pays. example: 66f2a3d1b4d3e80012c9a0d2 barcode: type: string description: >- The boleto's barcode (or digitable line), as the bank returned it. example: '34194162600001500001790010104351004791020150' type: type: string nullable: true enum: - GENERIC - UTILITY_BILL - null description: >- Kind of boleto: `GENERIC` (a bank boleto) or `UTILITY_BILL` (a utility or tax bill — energy, water, phone, taxes). A bank boleto can only be scheduled for its due date (or the next business day), or for any business day when it has no due date. `null` or absent when the bank didn't say. example: GENERIC status: type: string enum: - REQUESTED - PENDING_APPROVAL - CANCELLED - PAID - FAILED - REFUNDED - SCHEDULED - EXPIRED description: >- Status of the payment: - `REQUESTED` — created; its details can still be changed, and it can be sent for approval, confirmed or cancelled. - `PENDING_APPROVAL` — waiting for the approvers the business policy names. It is paid once approved. - `EXPIRED` — the approval deadline (`approvalExpiresAt`) passed while it was still waiting — also when it was approved but the policy's top-up of the wallet failed; the approval request (`policyRequestId`) tells which. - `SCHEDULED` — confirmed for a later day. On `scheduledAt`, a new payment is created and paid; this one stays `SCHEDULED`. - `PAID` — the bank accepted the payment; the money left the wallet. - `FAILED` — the payment was refused, for the reason in `failReason`. - `CANCELLED` — cancelled before it was paid. - `REFUNDED` — paid, then reversed by the bank; the amount was returned. example: REQUESTED payee: type: string nullable: true description: >- Name of the beneficiary — who receives the money (*beneficiário*). Empty or `null` when the bank didn't say. example: Gráfica Aurora Ltda payeeDocument: type: string nullable: true description: >- CPF or CNPJ of the beneficiary, digits only. Empty or `null` when the bank didn't say. example: '12345678000195' payer: type: string nullable: true description: >- Name of who the boleto was issued to (*pagador*). Empty or `null` when the bank didn't say. example: Acme Comércio Ltda payerDocument: type: string nullable: true description: >- CPF or CNPJ of who the boleto was issued to, digits only. Empty or `null` when the bank didn't say. example: '98765432000110' issuer: type: string nullable: true description: >- Bank that issued the boleto. `null` or absent when the bank didn't say. example: Itaú Unibanco S.A. txnCurrency: type: string description: >- Currency of the amounts, as an ISO 4217 numeric code: `986` (Brazilian real). example: '986' txnOriginalAmount: type: number description: Face value of the boleto, in cents. example: 150000 txnDiscountAmount: type: number description: >- Discount the boleto granted on the day the payment was created, in cents (not refreshed later). example: 0 txnFineAmount: type: number description: >- Late fine the boleto charged on the day the payment was created, in cents (not refreshed later). example: 0 txnInterestAmount: type: number description: >- Interest the boleto charged on the day the payment was created, in cents (not refreshed later). example: 0 txnUpdatedAmount: type: number description: >- Amount the boleto asked for when the payment was created, in cents — the face value with that day's discount, fine and interest applied. It isn't refreshed later: what will be paid is `pendingConfirmation.amount`, and what was paid, `confirmedAmount`. example: 150000 txnMinAmount: type: number description: >- Smallest amount the boleto accepts, in cents. `0` when it states none. example: 0 txnMaxAmount: type: number description: >- Largest amount the boleto accepts, in cents. `0` when it states none. example: 0 dueDate: type: string nullable: true description: >- Due date of the boleto (*vencimento*). `null` or absent when it has none — usual for utility and tax bills. example: '2026-11-10T00:00:00.000Z' format: date-time expiresAt: type: string nullable: true description: >- Last day the boleto can be paid (*data limite de pagamento*). `null` or absent when the bank didn't say. example: '2026-12-10T00:00:00.000Z' format: date-time settlesAt: type: string nullable: true description: >- Settlement date the bank reported for the boleto when it was looked up. `null` or absent when the bank didn't say. example: '2026-11-02T00:00:00.000Z' format: date-time receipt: type: object properties: authentication: type: string nullable: true description: >- Authentication code of the boleto, when the bank returned one. Usually empty before the payment. example: null authenticationApi: type: string nullable: true description: >- The bank's authentication data, as a JSON-encoded string, when it returned any. example: null receipt: type: string nullable: true description: Text of the receipt, when the bank returned one. example: null description: >- Authentication data the bank returned when the boleto was looked up. external: type: object properties: boletoId: type: string description: The bank's ID of the payment. example: 2f8d6c1a-4b3e-4a5d-9c7b-1e0f2a3b4c5d format: uuid platformUserId: type: string description: >- ID of the user who created the payment, on some older payments only. Use `requester`. example: e3553bc1-5e20-4e17-b22a-a796fda0aa99 description: References of the payment at the bank. pendingConfirmation: type: object properties: amount: type: number description: Amount to pay, in cents. example: 150000 category: type: string enum: - FLEX_NATIONAL - FLEX_INTERNATIONAL - FOOD - GAS - MOBILITY - TOLL - FLEX_NATIONAL_WITHOUT_WITHDRAWALS - ADS - SAAS - HOTEL - AIRLINES - TRAVEL - BLOCKED - CASHBACK description: >- Balance category of the wallet the payment is charged to. Until it is set, the payment can't be sent for approval or confirmed. example: FLEX_INTERNATIONAL description: type: string description: Description of the payment. example: Folders da campanha de novembro required: - amount description: >- What will be paid. Absent until an amount is known — when the boleto states none and none was sent, set it with `PUT .../boleto/{boletoId}` — and on payments created before it existed. customFields: type: object additionalProperties: {} description: >- Values of the organization's transaction custom fields, keyed by each field's `slug`. Absent when the payment has none. --- Example: `{"cost-center":"CC-1020"}` example: cost-center: CC-1020 requester: type: object properties: userId: type: string description: >- ID of the user or API client that created the payment. example: e3553bc1-5e20-4e17-b22a-a796fda0aa99 name: type: string description: >- Name of the user, as it was when they created the payment (their e-mail or ID when they have no name). example: Mariana Costa email: type: string description: >- E-mail of the user, as it was when they created the payment. example: mariana.costa@acme.com.br required: - userId - name - email description: >- Who created the payment. Absent on payments created before it was recorded. scheduledAt: type: string description: >- Day the payment is scheduled for. Absent when it is paid as soon as it is confirmed. example: '2026-11-10T00:00:00.000Z' format: date-time scheduledTimeZone: type: string description: >- Time zone `scheduledAt` was read in — always `America/Sao_Paulo`. Present only with `scheduledAt`. example: America/Sao_Paulo scheduleId: type: string description: >- ID of the schedule created when a payment for a later day was confirmed. Cancel the payment to cancel it. example: 8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f format: uuid policyRequestId: type: string description: >- ID of the approval request opened when the payment was sent for approval, or of the automatic approval that funded it. Absent otherwise. example: 4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a approvalExpiresAt: type: string description: >- Deadline for the approval: 21:00 (São Paulo time) of the day the payment is for, and at least one hour after it was sent for approval. Present once it was sent for approval. example: '2026-11-03T00:00:00.000Z' format: date-time autoResolutionRequestedAt: type: string description: >- When a confirmation first asked for the automatic approval of the matching business policy. Once set, every later confirmation of this payment follows that approval. Absent when no confirmation needed it. example: '2026-11-02T13:12:05.000Z' format: date-time autoResolutionInFlightUntil: type: string description: >- While set and in the future, a confirmation is carrying out the matching policy's automatic approval, and cancelling the payment is refused until then. example: '2026-11-02T13:13:35.000Z' format: date-time processingType: type: string enum: - INSTANT - DELAYED description: >- How the payment was made: `INSTANT` (when it was confirmed) or `DELAYED` (by a schedule, on its day). example: INSTANT confirmedAt: type: string nullable: true description: >- When the payment was made. `null` or absent until then. example: '2026-11-02T13:12:07.000Z' format: date-time confirmedAmount: type: number description: >- Amount paid, in cents. `0` until the payment is made. example: 0 confirmedBalanceCategory: type: string enum: - FLEX_NATIONAL - FLEX_INTERNATIONAL - FOOD - GAS - MOBILITY - TOLL - FLEX_NATIONAL_WITHOUT_WITHDRAWALS - ADS - SAAS - HOTEL - AIRLINES - TRAVEL - BLOCKED - CASHBACK description: >- Balance category of the wallet the payment was charged to. example: FLEX_INTERNATIONAL failReason: type: string description: >- Why the payment failed, as an error code — for example `LIMIT_EXCEEDED`, `INSUFFICIENT_FUNDS` or `REJECTED_BY_FRAUD`. Only on `FAILED` payments. example: INSUFFICIENT_FUNDS canceledAt: type: string nullable: true description: >- When the payment was cancelled. `null` or absent unless it was. example: '2026-11-02T15:40:00.000Z' format: date-time refundedAt: type: string description: When the bank reversed the payment. example: '2026-11-05T10:30:00.000Z' format: date-time createdAt: type: string description: When the payment was created. example: '2026-11-02T13:10:22.000Z' format: date-time updatedAt: type: string description: When the payment last changed. example: '2026-11-02T13:10:22.000Z' format: date-time __v: type: number description: Internal revision counter of the record. example: 0 required: - _id - environment - realmId - organizationId - accountId - walletId - barcode - status - payee - payeeDocument - payer - payerDocument - txnCurrency - txnOriginalAmount - txnDiscountAmount - txnFineAmount - txnInterestAmount - txnUpdatedAmount - txnMinAmount - txnMaxAmount - processingType - confirmedAmount - createdAt - updatedAt description: A boleto payment made from one of your wallets. description: The payments of this page, newest first. next: type: string nullable: true description: >- Cursor of the next page: send it as `next` to read it. `null` on the last page. example: NjcyNmIxYzJiNGQzZTgwMDEyYzlhNGEx required: - items - next description: A page of boleto payments. '422': description: >- `BAD_REQUEST` — The realm ID is not a valid UUID, or a query parameter is invalid; `fields` lists each one. content: application/json: schema: type: object properties: traceId: type: string description: >- Identifier of the request that failed. Quote it when contacting support. example: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: type: string enum: - BAD_REQUEST description: >- Stable, machine-readable error code. Branch on this, never on `message`. origin: type: string enum: - BANKING description: Service that produced the error. message: type: string description: >- Human-readable explanation. Its wording may change without notice. fields: type: array description: >- One entry per invalid request field (validation errors only). items: type: object properties: field: type: string description: >- Path of the invalid field, e.g. `label` or `values[0].value`. example: label message: type: string description: Why the field was rejected. example: label is required code: type: string description: >- `_` — e.g. `LABEL_REQUIRED`, `TYPE_ONE_OF`, `VALUES_VALUE_TYPE_ERROR`. example: LABEL_REQUIRED values: type: array items: type: string description: >- The accepted values, when the field is an enumeration. required: - field - message - code required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BAD_REQUEST origin: BANKING message: >- Bad Request: Your request is invalid or incomplete. Please make sure you are requesting with the right fields. fields: - field: limit message: 'Invalid input: expected integer, received string' code: LIMIT_TYPE_ERROR ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.