> ## 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. # Send a Pix payment for approval > Sends a Pix payment for approval, when the organization's business policies require it. Nothing is paid here: the payment becomes `PENDING_APPROVAL` and an approval request goes to the approvers the policy names. Once they approve it, the payment is confirmed automatically, with the details it had when it was sent; if they deny it, or the deadline (`approvalExpiresAt`) passes, it is not paid. Send no body. The payment must be `REQUESTED`, with its amount and balance category set (at creation or with `PUT .../pix/{pixId}`), and every required transaction custom field filled in. Its details can't change while it waits: to change them, cancel it and create another payment. Send it for approval only when the policies answer `NONE`: with `APPROVE`, confirm it instead; with `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 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}/request 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}/request: post: tags: - Pix Payments summary: Send a Pix payment for approval description: >- Sends a Pix payment for approval, when the organization's business policies require it. Nothing is paid here: the payment becomes `PENDING_APPROVAL` and an approval request goes to the approvers the policy names. Once they approve it, the payment is confirmed automatically, with the details it had when it was sent; if they deny it, or the deadline (`approvalExpiresAt`) passes, it is not paid. Send no body. operationId: >- postRealmsByRealmIdOrganizationsByOrganizationIdAccountsByAccountIdWalletsByWalletIdPixByPixIdRequest 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 responses: '201': 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: PENDING_APPROVAL 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: 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; 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 policyRequest: type: object properties: id: type: string description: >- ID of the approval request — the payment's `policyRequestId`. example: 4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a 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 account. example: 66f2a1c7b4d3e80012c9a0b4 walletId: type: string description: ID of the wallet that pays. example: 66f2a3d1b4d3e80012c9a0d2 walletName: type: string description: Name of that wallet. example: Marketing context: type: string description: 'Kind of operation: `PAYMENT`.' example: PAYMENT subjectType: type: string description: 'What is being approved: `PIX`.' example: PIX subjectId: type: string description: ID of the payment. example: 6726a4f1b4d3e80012c9a3f1 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. body: type: object additionalProperties: {} description: >- The payment as the approvers see it, with the details being approved in `confirmation`. policyId: type: string description: ID of the business policy that requires the approval. example: 3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f status: type: string description: >- Status of the approval request: `REQUESTED` while waiting, then `APPROVED`, `DENIED`, `CANCELED` or `EXPIRED`. example: REQUESTED executionMode: type: string description: >- Which part of the policy runs after approval. Absent when all of it runs. example: MOVE_BALANCE_ONLY executionStatus: type: string description: >- Progress of what runs after approval — the top-up, then the payment: `WAITING`, `PROCESSING`, `EXECUTED` or `FAILED`. example: WAITING approvalDeadline: type: string description: Deadline for the approval. example: '2026-11-03T00:00:00.000Z' format: date-time executionMoveBalance: 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: The policy's top-up, when it has one. approvalHierarchy: type: boolean description: >- Whether the approvals are decided one after the other, in order. example: false approvals: type: array items: type: object properties: type: type: string enum: - USER - GROUP description: >- `USER` for a user, `GROUP` for a group of users — any one of them decides. 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. example: Rafael Lima status: type: string enum: - WAITING - REQUESTED - APPROVED - DENIED - CANCELED description: >- Status of the approval: `WAITING` (its turn hasn't come, when approvers decide in order), `REQUESTED`, `APPROVED`, `DENIED` or `CANCELED`. example: REQUESTED users: type: array items: type: object properties: userId: type: string description: ID of the user. example: 0b6f2c1e-8d4a-4f3b-9a7e-5c2d1e0f9a8b format: uuid userName: type: string description: Name of the user. example: Rafael Lima userEmail: type: string description: E-mail of the user. example: rafael.lima@acme.com.br status: type: string enum: - WAITING - REQUESTED - APPROVED - DENIED - CANCELED description: >- The user's decision: `WAITING`, `REQUESTED`, `APPROVED`, `DENIED` or `CANCELED`. example: REQUESTED required: - userId - userName - userEmail - status description: A user who decides an approval. description: >- The users who can decide it: one for a user, every member for a group. createdAt: type: string description: When the approval was created. example: '2026-11-02T13:11:40.000Z' format: date-time requestedAt: type: string description: When the approval was asked of its users. example: '2026-11-02T13:11:40.000Z' format: date-time required: - type - id - name - status - users description: An approval the payment needs. description: The approvals the payment needs. createdAt: type: string description: When the approval request was created. example: '2026-11-02T13:11:40.000Z' format: date-time updatedAt: type: string description: When it last changed. example: '2026-11-02T13:11:40.000Z' format: date-time required: - id - realmId - organizationId - accountId - walletId - context - subjectType - subjectId - requester - body - policyId - status - executionStatus - approvalDeadline - approvalHierarchy - approvals description: The approval request opened for the payment. required: - _id - accountId - additionalInfo - confirmedAmount - createdAt - environment - initiationType - organizationId - policyRequest - processingType - realmId - refundedAmount - status - transactionType - txnCurrency - txnDiscountAmount - txnFineAmount - txnInterestAmount - txnOriginalAmount - txnPurchaseAmount - txnUpdatedAmount - txnWithdrawalAmount - updatedAt - walletId description: >- A Pix payment just sent for approval, with the approval request opened for it. '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_APPROVAL_NOT_REQUIRED` — The business policies approve the payment as it stands (or none matches): confirm it instead. `PIX_POLICY_DENIED` — A business policy refuses the 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: - FORBIDDEN_WALLET - PIX_APPROVAL_NOT_REQUIRED - PIX_POLICY_DENIED 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_NOT_REQUESTABLE` — The payment is no longer `REQUESTED`, or an approval request is already open for it with other details. `MOVE_BALANCE_PARAMETERS_CHANGED` — A confirmation already ran the matching policy's top-up for this payment, and 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: - PIX_NOT_REQUESTABLE - 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_NOT_REQUESTABLE origin: BANKING message: This pix is not in a requestable state '422': description: >- `BAD_REQUEST` — A path parameter 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. 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 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: organizationId message: Invalid UUID code: ORGANIZATIONID_UUID '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. 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's gateway failed 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: >- `POLICY_EVALUATION_UNAVAILABLE` — The business policies couldn't be evaluated. Nothing changed — retry shortly. `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: - POLICY_EVALUATION_UNAVAILABLE - 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's gateway timed out 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.