> ## 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 Pix payment > Confirms a Pix payment: the money leaves the wallet and goes to the recipient. Send no payment details — the confirmation pays what is stored in `pendingConfirmation` (set at creation or with `PUT .../pix/{pixId}`), 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 and tops up the wallet, the top-up runs first — except for a payment for a later day, which is not topped up here (one approved through an approval request is topped up when approved). An organization admin's confirmation of a payment the policy sends for approval, or refuses, gets no top-up. 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 `CONFIRMED`, and the policies' verdict in `policy`. It becomes `PAID` once the Pix network settles it. * **201** — a later day (`scheduledAt`): the schedule created for it. The payment becomes `SCHEDULED`; on that day a new payment is created and paid, without the custom fields — in an organization with a required transaction custom field, that payment fails. Cancel the payment to cancel the schedule. Only payments by Pix key or QR code can be scheduled: a payment by bank details for a later day is refused here and stays `REQUESTED`. When the payment is refused — 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. 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 Pix payments must be enabled in its settings. ## OpenAPI ````yaml /api-reference/banking.openapi.json post /realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}/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}/pix/{pixId}/confirm: post: tags: - Pix Payments summary: Confirm a Pix payment description: >- Confirms a Pix payment: the money leaves the wallet and goes to the recipient. Send no payment details — the confirmation pays what is stored in `pendingConfirmation` (set at creation or with `PUT .../pix/{pixId}`), so the amount and the balance category must already be set, and every required transaction custom field filled in. operationId: >- postRealmsByRealmIdOrganizationsByOrganizationIdAccountsByAccountIdWalletsByWalletIdPixByPixIdConfirm 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: pixId in: path required: true description: ID of the Pix payment — its `_id` (24 hexadecimal characters). schema: type: string pattern: ^[0-9a-fA-F]{24}$ example: 6726a4f1b4d3e80012c9a3f1 - 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 `{pixId}` in the payment endpoints. example: 6726a4f1b4d3e80012c9a3f1 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 initiationType: type: string enum: - DICT - DYNAMIC_QRCODE - STATIC_QRCODE - FULL_BANK_DETAILS description: >- How the payment was started: - `DICT` — by Pix key. - `DYNAMIC_QRCODE` — by a dynamic QR code (a charge, with or without a due date). - `STATIC_QRCODE` — by a static QR code. - `FULL_BANK_DETAILS` — by the recipient's bank details. A payment started from a Pix Copia e Cola code or a QR code of unknown kind shows the kind the code turned out to be. example: DICT transactionType: type: string enum: - TRANSFER - CHANGE - WITHDRAWAL - PAYMENT - TRANFER description: >- Kind of payment: `TRANSFER` (to a Pix key or bank details), `PAYMENT` (a QR code), `CHANGE` or `WITHDRAWAL` (a Pix Troco or Pix Saque QR code). One older payment carries `TRANFER`. example: TRANSFER status: type: string enum: - REQUESTED - PENDING_APPROVAL - CANCELLED - CONFIRMED - PAID - FAILED - REFUNDED - SCHEDULED - EXPIRED - PARTIALLY_REFUNDED 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 waited: it wasn't approved in time, or it was approved but the policy's top-up of the wallet failed. - `SCHEDULED` — confirmed for a future day. On `scheduledAt`, a new payment is created and paid (without this one's custom fields); this one stays `SCHEDULED`. - `CONFIRMED` — sent to the Pix network; the money left the wallet. - `PAID` — the Pix network settled it. - `FAILED` — the payment was refused, for the reason in `failReason`. - `CANCELLED` — cancelled before it was paid. - `REFUNDED` — paid, then returned in full or in part by the recipient's bank — see `refunds`. One older payment carries `PARTIALLY_REFUNDED`. example: CONFIRMED creditParty: type: object properties: _id: type: string description: Internal identifier of this entry. example: 6726a4f1b4d3e80012c9a3f2 name: type: string description: Name of the recipient. example: Gráfica Aurora Ltda document: type: string description: >- CPF or CNPJ of the recipient, digits only (a CNPJ may carry letters in its first 12 positions). example: '12345678000195' bankIspb: type: string description: >- ISPB code of the recipient's bank or payment institution (8 digits). example: '60746948' key: type: string description: >- Pix key the payment goes to. Empty for a payment by bank details. example: '12345678000195' keyType: type: string enum: - PHONE - EMAIL - CPF - CNPJ - EVP description: >- Type of `key`: `PHONE`, `EMAIL`, `CPF`, `CNPJ` or `EVP` (random key). Absent on many older payments. example: CNPJ accountType: type: string description: >- Type of the recipient's account, on a payment by bank details only: `CACC` (checking), `SLRY` (salary), `SVGS` (savings) or `TRAN` (payment account). example: CACC branch: type: string description: >- Branch of the recipient's account, on a payment by bank details only. example: '0001' accountNumber: type: string description: >- Number of the recipient's account, on a payment by bank details only. example: '123456' street: type: string nullable: true description: >- Street of the recipient, as the QR code states it. `null` when the QR code has none; absent on payments by key or bank details. example: Rua das Gráficas, 100 city: type: string nullable: true description: >- City of the recipient, as the QR code states it. `null` when the QR code has none; absent on payments by key or bank details. example: São Paulo state: type: string nullable: true description: >- State of the recipient, as the QR code states it. `null` when the QR code has none; absent on payments by key or bank details. example: SP postalCode: type: string nullable: true description: >- Postal code (CEP) of the recipient, as the QR code states it. `null` when the QR code has none; absent on payments by key or bank details. example: '01310100' description: Who receives the payment. Present on every payment so far. debitParty: type: object properties: _id: type: string description: Internal identifier of this entry. example: 6726a4f1b4d3e80012c9a3f3 name: type: string description: Name of the account holder. example: Acme Logística Ltda document: type: string description: CNPJ of the account holder, digits only. example: '98765432000110' bankIspb: type: string description: ISPB code of Portão 3's banking partner (8 digits). example: '12345678' accountType: type: string description: 'Type of the paying account: `TRAN` (payment account).' example: TRAN branch: type: string description: >- Branch of the paying account. Absent on some older payments. example: '0001' accountNumber: type: string description: >- Number of the paying account. Absent on some older payments. example: '9876543' key: type: string description: >- Pix key of the paying account, on a few older payments only. example: '98765432000110' description: The paying account. Present on every payment so far. description: type: string nullable: true description: >- Description of the payment, as sent to the Pix network. `null` or absent when there is none — QR codes may carry their own. example: Folders da campanha de novembro direction: type: string description: Always empty when present. Ignore it. example: '' receipt: type: object properties: endToEndId: type: string description: >- End-to-end ID of the payment in the Pix network (32 characters, starting with `E`) — the ID the recipient's bank shows. Usually assigned when the payment is created, and final once it is confirmed; empty on a payment by bank details until it is confirmed. example: E12345678202611021312k7Q2mX9pL4w description: >- The Pix network's proof of the payment. Absent on a few older payments. external: type: object properties: pixId: type: string description: >- ID of the payment at Portão 3's banking partner. You never need it to call this API: identify the payment by its `_id`. Absent on some older payments. example: c7810c30-971f-4e84-8feb-b7819087d4de format: uuid platformUserId: type: string description: >- ID of the user who created the payment, on some older payments only. example: e3553bc1-5e20-4e17-b22a-a796fda0aa99 description: >- References of the payment in the Pix network. Absent on some older payments. txnCurrency: type: string description: >- Currency of the amounts, as an ISO 4217 numeric code: `986` (Brazilian real). example: '986' txnAllowAmountChange: type: boolean description: >- Whether you can choose the amount to pay — `true` for a QR code with an open amount. When `false` (or absent, on a few older payments), the amount to pay is `txnUpdatedAmount` and no other amount is accepted — except that a `COBV` charge scheduled for its due date may also pay `txnOriginalAmount`. example: false txnOriginalAmount: type: number description: >- Amount when the payment was started, in cents: the amount you sent for a payment by key or bank details, or the QR code's original amount. `0` for a QR code with an open amount. example: 123000 txnDiscountAmount: type: number description: Discount the QR code grants, in cents. example: 0 txnFineAmount: type: number description: Late fine the QR code charges, in cents. example: 0 txnInterestAmount: type: number description: Interest the QR code charges, in cents. example: 0 txnPurchaseAmount: type: number description: Purchase amount of a Pix Troco QR code, in cents. example: 0 txnWithdrawalAmount: type: number description: Cash amount of a Pix Saque or Pix Troco QR code, in cents. example: 0 txnUpdatedAmount: type: number description: >- Amount the payment asks for, in cents — the original amount with the QR code's discount, fine and interest applied — as read when the payment was created. It isn't refreshed afterwards: for a charge whose fine or interest grows by the day, create a new payment to get the current figure. `0` for a QR code with an open amount. example: 123000 qrCodeType: type: string enum: - STATIC - COB - COBV description: >- Kind of QR code: `STATIC`, `COB` (a charge with no due date) or `COBV` (a charge with a due date, fine, interest and discount). Only on payments by QR code. example: COB pixCopyPaste: type: string description: >- The QR code's Pix Copia e Cola code. Only on payments by QR code. example: >- 00020101021226870014br.gov.bcb.pix2565qrcode.example.com/v2/cobv/9d36b84f5204000053039865802BR5919GRAFICA AURORA LTDA6009SAO PAULO62070503***6304ABCD dueDate: type: string nullable: true description: >- Due date of a QR code charge. `null` or absent when it has none. example: null format: date-time expiresAt: type: string nullable: true description: >- When the QR code stops being payable. `null` or absent when it doesn't expire. example: null format: date-time withdrawal: type: object properties: agentType: type: string nullable: true enum: - AGTEC - AGTOT - AGPSS - null description: >- Kind of agent that hands over the cash: `AGTEC` (a store), `AGTOT` (an ATM network or banking agent) or `AGPSS` (a withdrawal service provider). `null` when the QR code is not a withdrawal or change one. example: null serviceProvider: type: string nullable: true description: >- ISPB of the withdrawal service provider. `null` when the QR code has none. example: null description: >- Cash withdrawal or change details of a QR code. Only on payments by QR code. additionalInfo: type: array items: type: object properties: _id: type: string description: Internal identifier of this entry. example: 6726a4f1b4d3e80012c9a3f4 key: type: string description: Name of the information, as the QR code states it. example: Pedido value: type: string description: Value of the information. example: '4821' required: - key - value description: A piece of extra information the QR code carries. description: >- Extra information the QR code carries. Empty when it has none. pendingConfirmation: type: object properties: amount: type: number description: Amount to pay, in cents. example: 123000 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 the amount is known — a QR code with an open amount gets it from `PUT .../pix/{pixId}` — 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 future 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 sent: `INSTANT` (when it was confirmed) or `DELAYED` (by a schedule, on its day). example: INSTANT confirmedAt: type: string description: When the payment was sent to the Pix network. example: '2026-11-02T13:12:07.000Z' format: date-time confirmedAmount: type: number description: Amount sent, in cents. `0` until the payment is confirmed. example: 123000 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; some older ones hold a numeric code or an empty string. example: INSUFFICIENT_FUNDS canceledAt: type: string description: When the payment was cancelled. example: '2026-11-02T15:40:00.000Z' format: date-time refundedAt: type: string description: When the latest return happened. example: '2026-11-05T10:30:00.000Z' format: date-time refundedAmount: type: number description: >- Total returned so far, in cents, across every return. `0` when nothing was returned. example: 0 refundedReason: type: string description: >- Why the latest return happened — the same codes as `refunds[].reason`; some older payments hold them in lowercase. example: REFUND_REQUST_BY_END_CUSTOMER refunds: type: array items: type: object properties: external: type: object properties: id: type: string description: ID of the return at Portão 3's banking partner. example: 0f9e8d7c-6b5a-4c3d-8e2f-1a0b9c8d7e6f required: - id description: References of the return in the Pix network. endToEndId: type: string description: End-to-end ID of the return in the Pix network. example: D12345678202611051030aB3cD4eF5gH amount: type: number description: Amount returned, in cents. example: 1230 effectiveAt: type: string description: When the return happened. example: '2026-11-05T10:30:00.000Z' format: date-time reason: type: string description: >- Why the money was returned: `REFUND_REQUST_BY_END_CUSTOMER` (asked for by the recipient — the code is spelled this way), `BANK_ERROR`, `FRAUD` or `SPECIFIC_SERVICE_OFFERED_BY_CREDITOR_AGENT`. example: REFUND_REQUST_BY_END_CUSTOMER required: - external - amount description: One return of the payment by the recipient's bank. description: >- Every return of the payment, one entry per return. Absent until the first one. linkedPix: type: string description: ID of a related payment, on a few older payments only. example: 6726a4f1b4d3e80012c9a3f5 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 - additionalInfo - confirmedAmount - createdAt - environment - initiationType - organizationId - policy - processingType - realmId - refundedAmount - status - transactionType - txnCurrency - txnDiscountAmount - txnFineAmount - txnInterestAmount - txnOriginalAmount - txnPurchaseAmount - txnUpdatedAmount - txnWithdrawalAmount - updatedAt - walletId description: A Pix payment just confirmed. '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: 123000 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: `PIX_TRANSFER` (by Pix key) or `PIX_PAYMENT` (by QR code). example: PIX_TRANSFER 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 pixTransfer: type: object properties: id: type: string description: ID of the scheduled transfer. example: 1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d format: uuid transactionSchedule: type: string description: ID of its schedule. example: 8c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f format: uuid key: type: string description: Pix key of the recipient. example: '12345678000195' dictType: type: string description: >- Type of the key: `PHONE`, `EMAIL`, `CPF`, `CNPJ` or `EVP`. example: CNPJ initiationId: type: string description: ID of the Pix payment that was scheduled. example: 6726a4f1b4d3e80012c9a3f1 required: - id - transactionSchedule - key - dictType - initiationId description: >- The Pix key the schedule pays. Only on a payment by Pix key (`PIX_TRANSFER`). pixPayment: type: object properties: id: type: string description: ID of the scheduled 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 emv: type: string description: The QR code's Pix Copia e Cola code. example: >- 00020101021226870014br.gov.bcb.pix2565qrcode.example.com/v2/cobv/9d36b84f5204000053039865802BR5919GRAFICA AURORA LTDA6009SAO PAULO62070503***6304ABCD key: type: string description: Pix key of the recipient. example: '12345678000195' dueAt: type: string nullable: true description: >- Due date of the QR code charge. Absent or `null` when it has none. example: '2026-11-10T00:00:00.000Z' format: date-time expiresAt: type: string nullable: true description: >- When the QR code stops being payable. Absent or `null` when it doesn't expire. example: '2026-11-30T00:00:00.000Z' format: date-time minAmount: type: number description: >- Smallest amount the QR code accepts, in cents, when it states one. example: 123000 maxAmount: type: number description: >- Largest amount the QR code accepts, in cents, when it states one. example: 123000 type: type: string description: >- Kind of QR code: `QR_CODE_STATIC`, `QR_CODE_COB` or `QR_CODE_COBV`. example: QR_CODE_COBV initiationId: type: string description: ID of the Pix payment that was scheduled. example: 6726a4f1b4d3e80012c9a3f1 required: - id - transactionSchedule - emv - type - initiationId description: >- The QR code the schedule pays. Only on a payment by QR code (`PIX_PAYMENT`). required: - id - amount - scheduledAt - type - status - realm - organization - account - wallet - createdAt - updatedAt - createdBy - updatedBy description: >- The schedule created when a payment for a future 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 Pix is 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 Pix payments are turned off. `PIX_REQUIRES_APPROVAL` — A business policy requires approval: send the payment for approval instead. `PIX_POLICY_DENIED` — A business policy refuses the payment. `PIX_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 - PIX_REQUIRES_APPROVAL - PIX_POLICY_DENIED - PIX_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. `PIX_NOT_FOUND` — The wallet has no Pix 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 - PIX_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: >- `PIX_STATUS_NOT_REQUESTED` — The payment was already confirmed, scheduled, cancelled or failed, or another confirmation of it is under way. `PIX_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. 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: - PIX_STATUS_NOT_REQUESTED - PIX_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: PIX_STATUS_NOT_REQUESTED origin: BANKING message: Pix status cannot be different from requested. '422': description: >- `BAD_REQUEST` — A path parameter or `processingType` is invalid; `fields` lists each one. `PAYMENT_PARAMETERS_MISSING` — The amount or the balance category isn't set: set them with `PUT .../pix/{pixId}`. `CUSTOM_FIELD_IS_REQUIRED` — A required transaction custom field has no value; `fields` names it. Set it with `PUT .../pix/{pixId}`. `INVALID_SCHEDULED_AT` — The payment's day (`scheduledAt`) has passed. Set another with `PUT .../pix/{pixId}`. `SCHEDULED_AT_NOT_ALLOWED` — A QR code charge with a due date (`COBV`) can only be paid today or on its due date; the message names the due date. `INSUFFICIENT_FUNDS` — The wallet's balance doesn't cover the amount. The payment is now `FAILED`. `LIMIT_EXCEEDED` — The payment is above a Pix transaction limit. The payment is now `FAILED`. `REJECTED_BY_FRAUD` — The payment was refused for fraud risk. The payment is now `FAILED`. `rejected_by_antifraud_prevention_rules` — The Pix network's fraud prevention refused the payment. The payment is now `FAILED`. `QR_CODE_EXPIRED` — The QR code stopped being payable. The payment is now `FAILED`. `qr_code_removed_by_receiver` — The recipient cancelled the QR code. The payment is now `FAILED`. `BANKING_PROVIDER_VALIDATION_ERROR` — The Pix network 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_IS_REQUIRED - INVALID_SCHEDULED_AT - SCHEDULED_AT_NOT_ALLOWED - INSUFFICIENT_FUNDS - LIMIT_EXCEEDED - REJECTED_BY_FRAUD - rejected_by_antifraud_prevention_rules - QR_CODE_EXPIRED - qr_code_removed_by_receiver - 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 answered with a server error, 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 this API doesn't recognize while paying. 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: - 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's gateway failed. 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 (its gateway's own timeout says "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.