> ## 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. # Confirm a boleto payment > Confirms a boleto payment: the money leaves the wallet and the boleto is paid. Send no payment details — the confirmation pays what is stored in `pendingConfirmation` (set at creation or with `PUT .../boleto/{boletoId}`), so the amount and the balance category must already be set, and every required transaction custom field filled in. The organization's business policies are evaluated again first. You can confirm when they approve the payment (`APPROVE`, also when no policy matches); when they require approval (`NONE`), send the payment for approval instead — it is confirmed automatically once approved, and can't be confirmed by hand meanwhile. Organization admins — API clients included — can confirm whatever the policies decide, and get the verdict back in `policy`, but not a payment already waiting for approval. When the matching policy approves the payment (`APPROVE`) and tops up the wallet before paying, the top-up runs first — except when a payment for a later day is confirmed directly: it isn't topped up. An organization admin confirming a payment the policies send for approval (`NONE`) skips the top-up too. See [Business policies and approvals](https://developers.portao3.com.br/guides/policies-and-approvals.md) for the whole flow. The answer depends on the day to pay: * **200** — paid now: the payment, now `PAID`, and the policies' verdict in `policy`. * **201** — a later day (`scheduledAt`): the schedule created for it. The payment becomes `SCHEDULED`; on that day a new payment is created from the same barcode and paid, for the same amount. Cancel the payment to cancel the schedule. That day's payment is charged to the general-purpose balance category (`FLEX_INTERNATIONAL`) whatever category was set, and carries none of the payment's custom fields — so it fails when the organization has a required transaction custom field. The amount must be one the boleto accepts (between `txnMinAmount` and `txnMaxAmount`, when it states them): otherwise the confirmation answers `400` with `code` `INVALID_AMOUNT` and `origin` `SCHEDULING`, nothing is scheduled, and the payment keeps its status — a `REQUESTED` one can take another amount with `PUT .../boleto/{boletoId}`; one confirmed after its approval stays `PENDING_APPROVAL` until its deadline (cancel it and create another). When the bank refuses the payment — for example, for insufficient funds or a limit — it becomes `FAILED`, with the reason in `failReason`, and the error is returned. A `FAILED` payment can't be retried: create another one. Some of the bank's reasons come in lowercase (`maximum_value_exceeded_by_period`), with the message `Unknown error`: branch on `code`. 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 post /realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/boleto/{boletoId}/confirm 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}/confirm: post: tags: - Boleto Payments summary: Confirm a boleto payment description: >- Confirms a boleto payment: the money leaves the wallet and the boleto is paid. Send no payment details — the confirmation pays what is stored in `pendingConfirmation` (set at creation or with `PUT .../boleto/{boletoId}`), so the amount and the balance category must already be set, and every required transaction custom field filled in. operationId: >- postRealmsByRealmIdOrganizationsByOrganizationIdAccountsByAccountIdWalletsByWalletIdBoletoByBoletoIdConfirm 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: false content: application/json: schema: type: object properties: processingType: description: >- Leave it out (`INSTANT`). `DELAYED` is reserved for the scheduled payments Portão 3 makes on their day. example: INSTANT type: string enum: - INSTANT - DELAYED retryCount: description: >- Leave it out (`0`). Reserved for the scheduled payments Portão 3 makes on their day. example: 0 type: integer 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: PAID 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: 150000 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: description: >- The business policy evaluated on this confirmation, and what it decided. `null` when the payment was confirmed after its approval, and when an organization admin confirmed it while the policies couldn't be evaluated. 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 title: Policy evaluation nullable: true 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 just made. '201': description: Successful response content: application/json: schema: type: object properties: id: type: string description: ID of the schedule — the payment's `scheduleId`. example: 8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f format: uuid amount: type: number description: Amount in cents. example: 150000 scheduledAt: type: string description: When the payment is made. example: '2026-11-10T00:00:00.000Z' format: date-time type: type: string description: 'Kind of schedule: `BANK_SLIP_PAYMENT`.' example: BANK_SLIP_PAYMENT status: type: string description: 'Status of the schedule: `SCHEDULED` until it runs.' example: SCHEDULED description: type: string description: Description of the payment. Absent when it has none. example: Folders da campanha de novembro realm: type: string description: ID of the realm. example: f495ff0c-ab54-4f99-8e92-ca8682e4de9b format: uuid organization: type: string description: ID of the organization. example: c4bd3f21-dfbd-44e8-8055-68ba15bed410 format: uuid account: type: string description: ID of the account. example: 66f2a1c7b4d3e80012c9a0b4 wallet: type: string description: ID of the wallet that pays. example: 66f2a3d1b4d3e80012c9a0d2 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 the payment is charged to. example: FLEX_INTERNATIONAL retryCount: type: number nullable: true description: >- How many times running it was retried. Absent, or `null`, before it runs. example: null createdAt: type: string description: When the schedule was created. example: '2026-11-02T13:12:07.000Z' format: date-time updatedAt: type: string description: When it last changed. example: '2026-11-02T13:12:07.000Z' format: date-time createdBy: type: string description: Who created it. example: e3553bc1-5e20-4e17-b22a-a796fda0aa99 updatedBy: type: string description: Who last changed it. example: e3553bc1-5e20-4e17-b22a-a796fda0aa99 cancelledBy: type: string description: Who cancelled it. Absent unless cancelled. example: e3553bc1-5e20-4e17-b22a-a796fda0aa99 cancelledAt: type: string description: When it was cancelled. Absent unless cancelled. example: '2026-11-05T10:00:00.000Z' format: date-time bankSlip: type: object properties: id: type: string description: ID of the scheduled boleto payment. example: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d format: uuid transactionSchedule: type: string description: ID of its schedule. example: 8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f format: uuid barCode: type: string description: Barcode of the boleto. example: '34194162600001500001790010104351004791020150' type: type: string description: >- Kind of boleto: `GENERIC` (a bank boleto) or `UTILITY_BILL` / `UTILITY` (a utility or tax bill). example: GENERIC dueAt: type: string nullable: true description: >- Due date of the boleto. Absent or `null` when it has none. example: '2026-11-10T00:00:00.000Z' format: date-time expiresAt: type: string nullable: true description: >- Last day the boleto can be paid. Absent or `null` when it isn't known. example: '2026-12-10T00:00:00.000Z' format: date-time minAmount: type: number description: >- Smallest amount the boleto accepts, in cents, when it states one. example: 150000 maxAmount: type: number description: >- Largest amount the boleto accepts, in cents, when it states one. example: 150000 initiationId: type: string description: ID of the boleto payment that was scheduled. example: 6726b1c2b4d3e80012c9a4a1 required: - id - transactionSchedule - barCode - type description: The boleto the schedule pays. required: - id - amount - scheduledAt - type - status - realm - organization - account - wallet - createdAt - updatedAt - createdBy - updatedBy - bankSlip description: >- The schedule created when a boleto payment for a later day is confirmed. The payment itself is now `SCHEDULED`, with this schedule's `id` as its `scheduleId`. '400': description: >- `ACCOUNT_NOT_OPEN` — The account isn't open in this environment. `WALLET_NOT_ACTIVE` — The wallet isn't `ACTIVE`. `ACCOUNT_LIMITS_EXCEEDED` — The account's limits don't allow it: outgoing boleto payments are turned off, or the amount is above the maximum per payment. 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_OPEN - WALLET_NOT_ACTIVE - ACCOUNT_LIMITS_EXCEEDED 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_OPEN origin: BANKING message: Account not open '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. `BOLETO_REQUIRES_APPROVAL` — A business policy requires approval: send the payment for approval instead. `BOLETO_POLICY_DENIED` — A business policy refuses the payment. `BOLETO_PENDING_APPROVAL` — The payment is waiting for approval; it is confirmed automatically once approved. 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 - BOLETO_REQUIRES_APPROVAL - BOLETO_POLICY_DENIED - BOLETO_PENDING_APPROVAL 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: >- `INVALID_BANK_SLIP_STATE` — The payment was already paid, scheduled, cancelled or failed, or another confirmation of it is under way. `BOLETO_EXPIRED` — The approval deadline passed while the payment waited; it is now `EXPIRED`. `MOVE_BALANCE_IN_PROGRESS` — The matching policy's top-up of the wallet is still running. Retry shortly. `MOVE_BALANCE_PARAMETERS_CHANGED` — The policy's top-up already ran for other details of this payment, or the payment funded by it is now set for a later day. 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: - INVALID_BANK_SLIP_STATE - BOLETO_EXPIRED - MOVE_BALANCE_IN_PROGRESS - MOVE_BALANCE_PARAMETERS_CHANGED 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: INVALID_BANK_SLIP_STATE origin: BANKING message: Invalid bank slip state. '422': description: >- `BAD_REQUEST` — A path parameter, `processingType` or `retryCount` is invalid; `fields` lists each one. `PAYMENT_PARAMETERS_MISSING` — The amount or the balance category isn't set: set them with `PUT .../boleto/{boletoId}`. `CUSTOM_FIELD_INVALID_VALUE` — A required transaction custom field has no value; `fields` names it. Set it with `PUT .../boleto/{boletoId}`. `INVALID_SCHEDULED_AT` — The payment's day (`scheduledAt`) has passed. Set another with `PUT .../boleto/{boletoId}`. `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. `INSUFFICIENT_FUNDS` — The wallet's balance doesn't cover the amount. The payment is now `FAILED`. `LIMIT_EXCEEDED` — The payment is above a transaction limit at the bank. The payment is now `FAILED`. `maximum_value_exceeded_by_period` — The payment would exceed the amount the bank allows in the period. The payment is now `FAILED`. `maximum_value_exceeded` — The amount is above the maximum allowed. The payment is now `FAILED`. `value_is_less_than_minimum_allowed` — The amount is below the minimum allowed. The payment is now `FAILED`. `boleto_expired_and_cannot_be_settled_today` — The boleto is past its due date and can no longer be paid today. The payment is now `FAILED`. `REJECTED_BY_FRAUD` — The payment was refused for fraud risk. The payment is now `FAILED`. `ALREADY_PAID` — The boleto was already paid. The payment is now `FAILED`. `BANKING_PROVIDER_VALIDATION_ERROR` — The bank refused a field of the payment; `fields` names it. The payment is now `FAILED`. 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 - PAYMENT_PARAMETERS_MISSING - CUSTOM_FIELD_INVALID_VALUE - INVALID_SCHEDULED_AT - SCHEDULED_AT_NOT_ALLOWED - INSUFFICIENT_FUNDS - LIMIT_EXCEEDED - maximum_value_exceeded_by_period - maximum_value_exceeded - value_is_less_than_minimum_allowed - boleto_expired_and_cannot_be_settled_today - REJECTED_BY_FRAUD - ALREADY_PAID - BANKING_PROVIDER_VALIDATION_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. 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: processingType message: 'Invalid option: expected one of "INSTANT"|"DELAYED"' code: PROCESSINGTYPE_ONE_OF '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 failed, or didn't answer in time while the wallet was being read. If it happened while paying, the payment is now `FAILED` — check the wallet's statement before paying again, since the money may still go out. `BANKING_PROVIDER_INTEGRATION_ERROR` — The bank answered with an error Portão 3 doesn't recognize. The payment is now `FAILED`; if it persists, contact support with the `traceId`. 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 - 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_UNAVAILABLE origin: BANKING message: Banking provider temporarily unavailable, please retry '502': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The bank was unavailable. If it happened while paying, the payment is now `FAILED` — check the wallet's statement before paying again, since the money may still go out. 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: >- `POLICY_EVALUATION_UNAVAILABLE` — The business policies couldn't be evaluated. Nothing changed — retry shortly. `MOVE_BALANCE_FAILED` — The matching policy's top-up of the wallet failed, so nothing was paid. Retry later; if it keeps failing, contact support with the `traceId`. `BANKING_PROVIDER_UNAVAILABLE` — The bank was unavailable. If it happened while paying, the payment is now `FAILED` — check the wallet's statement before paying again, since the money may still go out. 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: - POLICY_EVALUATION_UNAVAILABLE - MOVE_BALANCE_FAILED - 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: POLICY_EVALUATION_UNAVAILABLE origin: BANKING message: The policy evaluation service is unavailable — please retry '504': description: >- `BANKING_PROVIDER_UNAVAILABLE` — The bank didn't answer in time — or was unavailable, with the message `Banking provider temporarily unavailable, please retry`. If it happened while paying, the payment is now `FAILED` — check the wallet's statement before paying again, since the money may still go out. 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 did not respond in time, please retry ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.