> ## 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. # Set a boleto payment's details > Sets what a boleto payment will pay: the amount, the balance category charged, the description, the custom fields and the day to pay. The payment must still be `REQUESTED`. The details you send replace the ones stored in `pendingConfirmation` — they are what sending the payment for approval or confirming it will use, since those take no details of their own. `amount` and `category` are required; usually the amount is the boleto's `txnUpdatedAmount`. The answer brings `policy`: what the organization's business policies say about the payment with these details. Read it to decide the next step — `APPROVE`: confirm the payment; `NONE`: send it for approval; `DENY`: it is refused. See [Business policies and approvals](https://developers.portao3.com.br/guides/policies-and-approvals.md) for the whole flow. You need permission to pay from the wallet: on the organization's main wallet, be an organization admin; on another wallet, be an organization admin or have it shared with you as `OWNER` or `USER` — and boleto payments must be enabled in its settings. ## OpenAPI ````yaml /api-reference/banking.openapi.json put /realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto/{boletoId} 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}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto/{boletoId}: put: tags: - Boleto Payments summary: Set a boleto payment's details description: >- Sets what a boleto payment will pay: the amount, the balance category charged, the description, the custom fields and the day to pay. The payment must still be `REQUESTED`. operationId: >- putRealmsByRealmIdOrganizationsByOrganizationIdAccountsByAccountIdWalletsByWalletIdBoletoByBoletoId 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: organizationId in: path required: true description: |- ID of the organization. Format: `UUID` schema: type: string format: uuid example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 - name: accountId in: path required: true description: ID of the organization's account (24 hexadecimal characters). schema: type: string pattern: ^[0-9a-fA-F]{24}$ example: 66f2a1c7b4d3e80012c9a0b4 - name: walletId in: path required: true description: >- ID of the wallet that pays (24 hexadecimal characters), or `default` for the organization's main wallet. schema: type: string pattern: ^([0-9a-fA-F]{24}|default)$ example: 66f2a3d1b4d3e80012c9a0d2 - name: boletoId in: path required: true description: ID of the boleto payment — its `_id` (24 hexadecimal characters). schema: type: string pattern: ^[0-9a-fA-F]{24}$ example: 6726b1c2b4d3e80012c9a4a1 - name: x-environment in: header required: false description: >- Environment of the payment: `LIVE` (production) or `TEST` (sandbox). When you omit it, `TEST` is used; any other value is rejected. schema: type: string enum: - LIVE - TEST example: LIVE requestBody: required: true content: application/json: schema: type: object properties: amount: type: integer minimum: 0 exclusiveMinimum: true description: >- Amount to pay, in cents — a positive integer. Usually the amount the boleto asks for today (`txnUpdatedAmount`); a boleto that accepts a range of amounts takes one between `txnMinAmount` and `txnMaxAmount`. The bank checks it when the payment is confirmed. example: 150000 category: type: string enum: - FLEX_NATIONAL - FLEX_INTERNATIONAL - FOOD - GAS - MOBILITY - TOLL - FLEX_NATIONAL_WITHOUT_WITHDRAWALS - ADS - SAAS - HOTEL - AIRLINES - TRAVEL description: >- Balance category of the wallet to charge. `FLEX_INTERNATIONAL` is the general-purpose one. example: FLEX_INTERNATIONAL description: description: >- A note kept with what will be paid. It isn't sent to the beneficiary. Leave it out to clear a previous one. example: Folders da campanha de novembro type: string customFields: description: >- Values of the organization's transaction custom fields, keyed by each field's `slug`. Replaces the whole set when sent; leave it out to keep the current values. Send `null`, `""` or `[]` as a value to clear that field. --- Example: `{"cost-center":"CC-1020"}` example: cost-center: CC-1020 type: object additionalProperties: {} scheduledAt: description: >- Day to pay, as `YYYY-MM-DD` (a date-time counts as its UTC day). A later day than today — in `timeZone` — makes the confirmation schedule the payment; today means "pay when confirmed" and clears a day set before. Leave it out to keep the current day. A day before today is rejected. A bank boleto (`type` `GENERIC`) can only be scheduled for a business day: its due date — or the next business day, when that falls on a weekend or holiday — or, when it has no due date, any business day; a utility or tax bill (`UTILITY_BILL`), for any later day. example: '2026-11-10' anyOf: - type: string format: date - type: string format: date-time timeZone: description: >- Time zone that decides what "today" is for `scheduledAt`. Only `America/Sao_Paulo` is supported: any other value, or none, is read as `America/Sao_Paulo`. Only read with `scheduledAt`. example: America/Sao_Paulo type: string required: - amount - category responses: '200': description: Successful response content: application/json: schema: 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 policy: anyOf: - type: object properties: actions: type: object properties: autoAction: type: string enum: - APPROVE - DENY - NONE description: >- `APPROVE` — the payment can be confirmed right away; `DENY` — it is refused; `NONE` — it needs approval from `approvals`: send it for approval. When no policy matches, this is `APPROVE` and no other field of the policy is present. example: NONE hierarchy: type: boolean description: >- Whether the approvers decide one after the other, in the order of `approvals`, instead of all at once. example: false moveBalance: type: object properties: addBalance: type: boolean description: >- Whether the policy adds the payment's amount to the wallet, from another wallet, before paying. example: true fromAccountId: type: string description: >- Account the top-up comes from. Present when `addBalance` is `true`. example: 66f2a1c7b4d3e80012c9a0b4 fromWalletId: type: string description: >- Wallet the top-up comes from. Present when `addBalance` is `true`. example: 66f2a1d0b4d3e80012c9a0b9 required: - addBalance description: >- Whether the policy tops up the wallet before the payment. approvals: type: array items: type: object properties: type: type: string enum: - USER - GROUP description: >- `USER` for a user, `GROUP` for a group of users. example: USER id: type: string description: ID of the user or of the group. example: 0b6f2c1e-8d4a-4f3b-9a7e-5c2d1e0f9a8b name: type: string description: >- Name of the user or of the group. Absent when it can't be read at that moment. example: Rafael Lima required: - type - id description: An approver named by a business policy. description: >- Who must approve the payment. Present when `autoAction` is `NONE`. required: - autoAction description: What the policy decides. id: type: string description: ID of the policy. example: 3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f 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 context: type: string description: >- Kind of operation the policy governs: `PAYMENT` for payments and transfers. example: PAYMENT name: type: string description: Name of the policy. example: Pagamentos acima de R$ 1.000 description: type: string description: Description of the policy. example: >- Pede aprovação do financeiro para pagamentos acima de R$ 1.000. order: type: number description: >- Position of the policy in the organization's evaluation order; the first that matches wins. example: 1 status: type: string description: Status of the policy. example: ACTIVE conditions: type: object properties: logic: type: string enum: - AND - OR description: >- `AND` — every group must match; `OR` — any one is enough. example: AND groups: type: array items: type: object properties: logic: type: string enum: - AND - OR description: >- `AND` — every condition must match; `OR` — any one is enough. example: AND dependsOn: type: array items: type: string description: |- Other groups this group depends on. --- Example: `[]` example: [] items: type: array items: type: object properties: operator: type: string description: >- How the field is compared, such as `GREATER_THAN` or `EQUALS`. example: GREATER_THAN field: type: string description: >- Field of the payment the condition reads. example: amount maskType: type: string description: >- Format the value is compared in, when the field needs one. example: CURRENCY dynamicFieldValue: type: string description: >- Another field whose value is compared instead of `value`. example: customFields.cost-center value: description: Value the field is compared with. example: 100000 required: - operator - field description: One condition of a business policy. description: The conditions of the group. required: - logic - items description: A group of conditions of a business policy. description: >- The groups of conditions. With none, the policy matches every payment. required: - logic - groups description: The conditions the policy matches. createdAt: type: string description: When the policy was created. example: '2026-09-15T14:00:00.000Z' format: date-time updatedAt: type: string description: When the policy last changed. example: '2026-10-01T09:30:00.000Z' format: date-time required: - actions description: >- The organization's business policy that matches the payment, and what it decides. When no policy matches, only `actions.autoAction` (`APPROVE`) is present. title: Policy evaluation - type: object properties: error: type: string description: Always `POLICY_EVALUATION_UNAVAILABLE`. example: POLICY_EVALUATION_UNAVAILABLE required: - error description: >- The organization's business policies couldn't be evaluated at that moment. The payment was still saved; set its details again to get a new evaluation, or go ahead — sending it for approval and confirming it evaluate the policies anew. title: Evaluation unavailable description: >- The business policy that matches the payment as it stands, and what it decides: the payment can be confirmed right away (`APPROVE`), it needs approval (`NONE`) or it is refused (`DENY`). Informative only — nothing is enforced until the payment is sent for approval or confirmed. required: - _id - accountId - barcode - confirmedAmount - createdAt - environment - organizationId - payee - payeeDocument - payer - payerDocument - policy - processingType - realmId - status - txnCurrency - txnDiscountAmount - txnFineAmount - txnInterestAmount - txnMaxAmount - txnMinAmount - txnOriginalAmount - txnUpdatedAmount - updatedAt - walletId description: >- A boleto payment, with what the organization's business policies say about it. examples: policy-evaluation: summary: Policy evaluation value: _id: 6726b1c2b4d3e80012c9a4a1 environment: LIVE realmId: f495ff0c-ab54-4f99-8e92-ca8682e4de9b organizationId: c4bd3f21-dfbd-44e8-8055-68ba15bed410 accountId: 66f2a1c7b4d3e80012c9a0b4 walletId: 66f2a3d1b4d3e80012c9a0d2 barcode: '34194162600001500001790010104351004791020150' type: GENERIC status: REQUESTED payee: Gráfica Aurora Ltda payeeDocument: '12345678000195' payer: Acme Comércio Ltda payerDocument: '98765432000110' issuer: Itaú Unibanco S.A. txnCurrency: '986' txnOriginalAmount: 150000 txnDiscountAmount: 0 txnFineAmount: 0 txnInterestAmount: 0 txnUpdatedAmount: 150000 txnMinAmount: 0 txnMaxAmount: 0 dueDate: '2026-11-10T00:00:00.000Z' expiresAt: '2026-12-10T00:00:00.000Z' settlesAt: '2026-11-02T00:00:00.000Z' receipt: authentication: null authenticationApi: null receipt: null external: boletoId: 2f8d6c1a-4b3e-4a5d-9c7b-1e0f2a3b4c5d platformUserId: e3553bc1-5e20-4e17-b22a-a796fda0aa99 pendingConfirmation: amount: 150000 category: FLEX_INTERNATIONAL description: Folders da campanha de novembro customFields: cost-center: CC-1020 requester: userId: e3553bc1-5e20-4e17-b22a-a796fda0aa99 name: Mariana Costa email: mariana.costa@acme.com.br scheduledAt: '2026-11-10T00:00:00.000Z' scheduledTimeZone: America/Sao_Paulo scheduleId: 8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f policyRequestId: 4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a approvalExpiresAt: '2026-11-03T00:00:00.000Z' autoResolutionRequestedAt: '2026-11-02T13:12:05.000Z' autoResolutionInFlightUntil: '2026-11-02T13:13:35.000Z' processingType: INSTANT confirmedAt: '2026-11-02T13:12:07.000Z' confirmedAmount: 0 confirmedBalanceCategory: FLEX_INTERNATIONAL failReason: INSUFFICIENT_FUNDS canceledAt: '2026-11-02T15:40:00.000Z' refundedAt: '2026-11-05T10:30:00.000Z' createdAt: '2026-11-02T13:10:22.000Z' updatedAt: '2026-11-02T13:10:22.000Z' __v: 0 policy: actions: autoAction: NONE hierarchy: false moveBalance: addBalance: true fromAccountId: 66f2a1c7b4d3e80012c9a0b4 fromWalletId: 66f2a1d0b4d3e80012c9a0b9 approvals: - type: USER id: 0b6f2c1e-8d4a-4f3b-9a7e-5c2d1e0f9a8b name: Rafael Lima id: 3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f realmId: f495ff0c-ab54-4f99-8e92-ca8682e4de9b organizationId: c4bd3f21-dfbd-44e8-8055-68ba15bed410 context: PAYMENT name: Pagamentos acima de R$ 1.000 description: >- Pede aprovação do financeiro para pagamentos acima de R$ 1.000. order: 1 status: ACTIVE conditions: logic: AND groups: - logic: AND dependsOn: [] items: - operator: GREATER_THAN field: amount maskType: CURRENCY dynamicFieldValue: customFields.cost-center value: 100000 createdAt: '2026-09-15T14:00:00.000Z' updatedAt: '2026-10-01T09:30:00.000Z' evaluation-unavailable: summary: Evaluation unavailable value: _id: 6726b1c2b4d3e80012c9a4a1 environment: LIVE realmId: f495ff0c-ab54-4f99-8e92-ca8682e4de9b organizationId: c4bd3f21-dfbd-44e8-8055-68ba15bed410 accountId: 66f2a1c7b4d3e80012c9a0b4 walletId: 66f2a3d1b4d3e80012c9a0d2 barcode: '34194162600001500001790010104351004791020150' type: GENERIC status: REQUESTED payee: Gráfica Aurora Ltda payeeDocument: '12345678000195' payer: Acme Comércio Ltda payerDocument: '98765432000110' issuer: Itaú Unibanco S.A. txnCurrency: '986' txnOriginalAmount: 150000 txnDiscountAmount: 0 txnFineAmount: 0 txnInterestAmount: 0 txnUpdatedAmount: 150000 txnMinAmount: 0 txnMaxAmount: 0 dueDate: '2026-11-10T00:00:00.000Z' expiresAt: '2026-12-10T00:00:00.000Z' settlesAt: '2026-11-02T00:00:00.000Z' receipt: authentication: null authenticationApi: null receipt: null external: boletoId: 2f8d6c1a-4b3e-4a5d-9c7b-1e0f2a3b4c5d platformUserId: e3553bc1-5e20-4e17-b22a-a796fda0aa99 pendingConfirmation: amount: 150000 category: FLEX_INTERNATIONAL description: Folders da campanha de novembro customFields: cost-center: CC-1020 requester: userId: e3553bc1-5e20-4e17-b22a-a796fda0aa99 name: Mariana Costa email: mariana.costa@acme.com.br scheduledAt: '2026-11-10T00:00:00.000Z' scheduledTimeZone: America/Sao_Paulo scheduleId: 8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f policyRequestId: 4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a approvalExpiresAt: '2026-11-03T00:00:00.000Z' autoResolutionRequestedAt: '2026-11-02T13:12:05.000Z' autoResolutionInFlightUntil: '2026-11-02T13:13:35.000Z' processingType: INSTANT confirmedAt: '2026-11-02T13:12:07.000Z' confirmedAmount: 0 confirmedBalanceCategory: FLEX_INTERNATIONAL failReason: INSUFFICIENT_FUNDS canceledAt: '2026-11-02T15:40:00.000Z' refundedAt: '2026-11-05T10:30:00.000Z' createdAt: '2026-11-02T13:10:22.000Z' updatedAt: '2026-11-02T13:10:22.000Z' __v: 0 policy: error: POLICY_EVALUATION_UNAVAILABLE '403': description: >- `FORBIDDEN_WALLET` — You can't pay from this wallet: on the organization's main wallet you aren't an organization admin; on another wallet you aren't an organization admin and it isn't shared with you as `OWNER` or `USER`, or its boleto payments are turned off. 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: - FORBIDDEN_WALLET 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. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: FORBIDDEN_WALLET origin: BANKING message: >- You do not have permission to perform this action on this wallet '404': description: >- `ACCOUNT_NOT_FOUND` — No account with this ID exists in the organization. `WALLET_NOT_FOUND` — No wallet with this ID exists in the account and environment. `BANK_SLIP_NOT_FOUND` — The wallet has no boleto payment with this ID in this environment. 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: - ACCOUNT_NOT_FOUND - WALLET_NOT_FOUND - BANK_SLIP_NOT_FOUND 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. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: ACCOUNT_NOT_FOUND origin: BANKING message: Account not found '409': description: >- `BOLETO_NOT_REQUESTABLE` — The payment is no longer `REQUESTED`: it was sent for approval, paid, scheduled, cancelled, failed or expired. To change a payment waiting for approval, cancel it and create another. 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: - BOLETO_NOT_REQUESTABLE 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. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BOLETO_NOT_REQUESTABLE origin: BANKING message: This boleto is not in a requestable state '422': description: >- `BAD_REQUEST` — A path or body field is invalid — `amount` and `category` are required; `fields` lists each one. `INVALID_SCHEDULED_AT` — `scheduledAt` is a day before today. `SCHEDULED_AT_NOT_ALLOWED` — A bank boleto (`GENERIC`) can only be scheduled for a business day: its due date — or the next business day, when that falls on a weekend or holiday — or, when it has no due date, any business day. The message names the allowed day. `CUSTOM_FIELD_NOT_FOUND` — A `customFields` key isn't the slug of one of the organization's transaction custom fields; `fields` names it. (When the organization has no transaction custom fields at all, the keys are stored as sent.) `CUSTOM_FIELD_NOT_ALLOWED` — A custom field in `customFields` isn't a transaction custom field; `fields` names it. `CUSTOM_FIELD_INVALID_VALUE` — A value in `customFields` doesn't fit its field's type or options, or a required field is sent with no value (`null`, `""` or `[]`); `fields` names it. 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 - INVALID_SCHEDULED_AT - SCHEDULED_AT_NOT_ALLOWED - CUSTOM_FIELD_NOT_FOUND - CUSTOM_FIELD_NOT_ALLOWED - CUSTOM_FIELD_INVALID_VALUE 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: amount message: 'Invalid input: expected integer, received undefined' code: AMOUNT_REQUIRED '429': description: >- `BANKING_PROVIDER_INTEGRATION_ERROR` — Too many requests reached the wallet's balance at once. Retry shortly. 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: - BANKING_PROVIDER_INTEGRATION_ERROR 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. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_INTEGRATION_ERROR origin: BANKING message: Too Many Requests '500': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The bank didn't answer in time while the wallet was being read. Nothing changed — retry. 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: - BANKING_PROVIDER_UNAVAILABLE 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. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider temporarily unavailable, please retry '502': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The bank was unavailable while the wallet was being read. Nothing changed — retry. 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: - BANKING_PROVIDER_UNAVAILABLE 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. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider temporarily unavailable, please retry '503': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The bank was unavailable while the wallet was being read. Nothing changed — retry. 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: - BANKING_PROVIDER_UNAVAILABLE 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. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider temporarily unavailable, please retry '504': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The bank was unavailable while the wallet was being read. Nothing changed — retry. 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: - BANKING_PROVIDER_UNAVAILABLE 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. required: - traceId - code - origin - message example: traceId: 1-68ee2a1b-3c4d5e6f7a8b9c0d1e2f3a4b code: BANKING_PROVIDER_UNAVAILABLE origin: BANKING message: Banking provider temporarily unavailable, please retry ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.