> ## 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. # Políticas de negócio e aprovações > Como as políticas da sua organização decidem se um pagamento Pix ou de boleto é pago na hora, precisa de aprovação ou é recusado Os administradores de uma organização escrevem **políticas de negócio** — regras como "pagamentos Pix acima de R\$ 1.000 precisam da aprovação do time financeiro" ou "nenhum pagamento da carteira de Marketing nos fins de semana". Todo pagamento Pix e de boleto feito a partir das carteiras da organização é verificado contra essas políticas, e a política correspondente decide o que acontece com ele. Este guia mostra como ler essa decisão e agir de acordo: crie o pagamento, defina seus detalhes e então **confirme-o** na hora ou **envie-o para aprovação**. > [!NOTE] > > As etapas abaixo usam um pagamento Pix. Pagamentos de boleto seguem as mesmas políticas e o mesmo fluxo — criar → definir os detalhes → enviar para aprovação ou confirmar —, com seus próprios endpoints e códigos de erro. Veja [Pagamentos de boleto](#pagamentos-de-boleto). > > Solicitações de transferência entre carteiras passam pelas mesmas políticas e pelas mesmas etapas de enviar para aprovação ou confirmar, com seus próprios endpoints e códigos de erro. As principais diferenças: o valor e a categoria de saldo são definidos na criação — para mudá-los, cancele a solicitação e crie outra — e só administradores da organização podem cancelá-las. ## O que uma política decide As políticas da organização são avaliadas na ordem definida por `order`, e a **primeira cujas condições correspondem** ao pagamento decide. As condições leem o pagamento como ele está: o valor, a categoria de saldo debitada, o destinatário, a carteira pagadora, quem o criou, seus campos personalizados e quantos dias faltam para o vencimento. A decisão é o `actions.autoAction` da política: | `autoAction` | Significado | O que você faz | | - | - | - | | `APPROVE` | O pagamento é permitido. É também a resposta quando **nenhuma política corresponde**. | [Confirme-o](#etapa-3a-confirmar-o-pagamento) — o dinheiro é movimentado. | | `NONE` | O pagamento precisa da aprovação das pessoas ou grupos em `actions.approvals`. | [Envie-o para aprovação](#etapa-3b-enviar-o-pagamento-para-aprovação) — ele é pago depois de aprovado. | | `DENY` | O pagamento é recusado. | Nada — ele não pode ser pago, exceto por um [admin da organização](#administradores-da-organização). [Cancele-o](https://developers.portao3.com.br/api-reference/banking/pix-payments/cancel-a-pix-payment.md) para encerrá-lo. | Uma política também pode **recarregar a carteira** antes de pagar (`actions.moveBalance`): o valor do pagamento é primeiro movido de outra carteira para a carteira pagadora e, então, pago. Isso acontece automaticamente quando um pagamento aprovado pela política é confirmado, e quando uma solicitação de aprovação é aprovada — você não precisa fazer nada a mais. Um administrador da organização que confirma um pagamento que a política enviaria para aprovação, ou recusaria, não tem recarga. Um pagamento para um dia futuro (`scheduledAt`) que você confirma diretamente não é recarregado — garanta que a carteira tenha o dinheiro nesse dia; um que passa por aprovação é recarregado quando é aprovado. Os administradores gerenciam as políticas no aplicativo do Portão 3 ou pelos endpoints de [políticas de negócio](https://developers.portao3.com.br/api-reference/ruleengine/business-policies/realms-organizations-business-policies.md) da API do Rule Engine. ## O fluxo ```mermaid theme={null} flowchart TD A["POST .../pix
criar o pagamento"] --> B{"valor e categoria
definidos?"} B -- não --> C["PUT .../pix/{pixId}
definir os detalhes"] B -- sim --> D{"policy.actions.autoAction"} C --> D D -- APPROVE --> E["POST .../pix/{pixId}/confirm
o dinheiro é movimentado"] D -- NONE --> F["POST .../pix/{pixId}/request
PENDING_APPROVAL"] D -- DENY --> G["recusado —
cancele-o"] F -- aprovado --> H["confirmado automaticamente
CONFIRMED, depois PAID"] F -- negado --> I["CANCELLED"] F -- prazo vencido --> J["EXPIRED"] ``` Toda etapa responde com o pagamento, então você sempre sabe o `status` dele. ## Etapa 1: Criar o pagamento [Crie o pagamento Pix](https://developers.portao3.com.br/api-reference/banking/pix-payments/create-a-pix-payment.md) com o destinatário — uma chave Pix, um Pix Copia e Cola / QR Code ou dados bancários. Nada é pago ainda: o pagamento começa como `REQUESTED`. ```bash theme={null} curl -X POST \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix' \ -H 'Authorization: Bearer ' \ -H 'x-environment: LIVE' \ -H 'Content-Type: application/json' \ -d '{ "initiationType": "DICT", "dict": "CNPJ", "key": "12345678000195", "amount": 123000, "category": "FLEX_INTERNATIONAL", "description": "Folders da campanha de novembro" }' ``` A resposta traz o pagamento e `policy` — o que as políticas dizem sobre ele **como ele está agora**: ```json theme={null} { "_id": "6726a4f1b4d3e80012c9a3f1", "status": "REQUESTED", "txnUpdatedAmount": 123000, "creditParty": { "name": "Gráfica Aurora Ltda", "key": "12345678000195" }, "pendingConfirmation": { "amount": 123000, "category": "FLEX_INTERNATIONAL", "description": "Folders da campanha de novembro" }, "policy": { "id": "3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f", "name": "Pagamentos acima de R$ 1.000", "actions": { "autoAction": "NONE", "hierarchy": false, "approvals": [{ "type": "USER", "id": "0b6f2c1e-8d4a-4f3b-9a7e-5c2d1e0f9a8b", "name": "Rafael Lima" }] } } } ``` Use o `_id` como `{pixId}` nas próximas etapas. ## Etapa 2: Definir os detalhes e ler o veredito `pendingConfirmation` guarda **o que será pago** — o valor, a categoria de saldo debitada e uma descrição. Enviar para aprovação e confirmar não recebem detalhes próprios: usam estes. Se você enviou `amount` e `category` na criação (como acima), eles já estão definidos e `policy` já os reflete — vá para a etapa 3. Caso contrário — normalmente um QR Code, cujo valor você só conhece depois de lê-lo, ou uma criação sem `category` —, [defina os detalhes](https://developers.portao3.com.br/api-reference/banking/pix-payments/set-a-pix-payments-details.md): ```bash theme={null} curl -X PUT \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}' \ -H 'Authorization: Bearer ' \ -H 'x-environment: LIVE' \ -H 'Content-Type: application/json' \ -d '{ "amount": 123000, "category": "FLEX_INTERNATIONAL", "customFields": { "cost-center": "CC-1020" } }' ``` A resposta traz o pagamento atualizado e uma `policy` nova. **Leia `policy.actions.autoAction` da resposta mais recente** para escolher entre a etapa 3a, a 3b ou nenhuma (`DENY`). Você pode chamar o `PUT` quantas vezes precisar enquanto o pagamento estiver `REQUESTED`. > [!TIP] > > A menos que o QR Code tenha valor aberto (`txnAllowAmountChange: true`), `amount` deve ser o `txnUpdatedAmount` do pagamento (uma cobrança `COBV` agendada para o vencimento também pode pagar o seu `txnOriginalAmount`). Preencha aqui também todos os campos personalizados obrigatórios da transação — confirmar e enviar para aprovação recusam um pagamento em que falte algum deles. ## Etapa 3a: Confirmar o pagamento Quando o veredito for `APPROVE`, [confirme o pagamento](https://developers.portao3.com.br/api-reference/banking/pix-payments/confirm-a-pix-payment.md). Não envie corpo: ```bash theme={null} curl -X POST \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}/confirm' \ -H 'Authorization: Bearer ' \ -H 'x-environment: LIVE' ``` As políticas são avaliadas mais uma vez, com os detalhes armazenados. Se elas ainda aprovarem, o dinheiro é movimentado: a resposta é **200** com o pagamento `CONFIRMED` — ele passa a `PAID` quando a rede Pix o liquida. Se o pagamento for para um dia futuro (`scheduledAt`), a resposta é **201** com o agendamento, e o pagamento passa a `SCHEDULED`. Se agora uma política exigir aprovação, a confirmação é recusada com `403 PIX_REQUIRES_APPROVAL` — envie o pagamento para aprovação. Se uma política recusar o pagamento, você recebe `403 PIX_POLICY_DENIED`. ## Etapa 3b: Enviar o pagamento para aprovação Quando o veredito for `NONE`, [envie o pagamento para aprovação](https://developers.portao3.com.br/api-reference/banking/pix-payments/send-a-pix-payment-for-approval.md). Não envie corpo: ```bash theme={null} curl -X POST \ 'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}/request' \ -H 'Authorization: Bearer ' \ -H 'x-environment: LIVE' ``` O pagamento passa a `PENDING_APPROVAL`, e uma **solicitação de aprovação** é aberta para os aprovadores que a política indica. A resposta traz essa solicitação em `policyRequest`: ```json theme={null} { "_id": "6726a4f1b4d3e80012c9a3f1", "status": "PENDING_APPROVAL", "policyRequestId": "4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "approvalExpiresAt": "2026-11-03T00:00:00.000Z", "policyRequest": { "id": "4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a", "status": "REQUESTED", "approvalHierarchy": false, "approvals": [ { "type": "USER", "id": "0b6f2c1e-8d4a-4f3b-9a7e-5c2d1e0f9a8b", "name": "Rafael Lima", "status": "REQUESTED", "users": [] } ] } } ``` A partir daqui: * **Os detalhes ficam congelados.** Os aprovadores aprovam exatamente o valor, a categoria e a descrição que o pagamento tinha quando foi enviado. Para alterá-los, [cancele o pagamento](https://developers.portao3.com.br/api-reference/banking/pix-payments/cancel-a-pix-payment.md) — a solicitação de aprovação dele também é cancelada — e crie um novo. * **Os aprovadores decidem.** Eles são notificados no aplicativo do Portão 3 e aprovam ou negam por lá, ou pela API do Rule Engine, ao [aprovar](https://developers.portao3.com.br/api-reference/ruleengine/policy-requests/realms-organizations-policy-requests-approve.md) ou [negar](https://developers.portao3.com.br/api-reference/ruleengine/policy-requests/realms-organizations-policy-requests-deny.md) a solicitação de aprovação cujo `id` é o `policyRequestId` do pagamento. Com `approvalHierarchy: true`, eles decidem um depois do outro, em ordem. Administradores da organização podem decidir qualquer solicitação sozinhos: [forçar a aprovação](https://developers.portao3.com.br/api-reference/ruleengine/policy-requests/realms-organizations-policy-requests-force-approve.md) ou [forçar a negação](https://developers.portao3.com.br/api-reference/ruleengine/policy-requests/realms-organizations-policy-requests-force-deny.md). * **Aprovado → pago.** Quando todas as aprovações são dadas, o Portão 3 confirma o pagamento por você, com os detalhes aprovados — sem nenhuma chamada sua. Ele passa a `CONFIRMED` e depois a `PAID` (ou a `SCHEDULED`, se for para um dia futuro). Se o pagamento for recusado nesse momento — por saldo insuficiente, por exemplo —, ele passa a `FAILED`, com o motivo em `failReason`. * **Aprovado, mas não executado.** Se a recarga da carteira prevista na política não puder ser feita depois da aprovação, o pagamento não é enviado. Alguns problemas detectados antes de qualquer dinheiro se mover são tentados de novo automaticamente (o `executionStatus` da solicitação de aprovação volta a `WAITING`). Qualquer outra falha — inclusive um timeout ou um erro do banco durante a recarga — encerra a solicitação com `executionStatus: FAILED` e o motivo em `executionFailReason`, e o pagamento fica `PENDING_APPROVAL` até o prazo, quando passa a aparecer como `EXPIRED`. A recarga pode ter acontecido: confira os saldos das carteiras antes de cancelar o pagamento e criar outro, e fale com o suporte se o dinheiro tiver sido movido. * **Negado → cancelado.** O pagamento passa a `CANCELLED`. * **Prazo vencido → expirado.** O prazo é `approvalExpiresAt`: 21h (horário de São Paulo) do dia do pagamento, e no mínimo uma hora depois do envio. Um pagamento que ainda estiver aguardando nesse momento passa a `EXPIRED`. Enquanto aguarda, o pagamento não pode ser confirmado manualmente — nem por um administrador da organização (`403 PIX_PENDING_APPROVAL`): a solicitação de aprovação é o registro da decisão. Para acompanhar o resultado, [consulte o pagamento](https://developers.portao3.com.br/api-reference/banking/pix-payments/get-a-pix-payment.md) até que o `status` dele saia de `PENDING_APPROVAL`, [consulte a solicitação de aprovação](https://developers.portao3.com.br/api-reference/ruleengine/policy-requests/realms-organizations-policy-requests-2.md) para ver quem decidiu o quê ou assine o [webhook](https://developers.portao3.com.br/pt-BR/guides/webhooks.md) `PIX_OUT`, enviado quando o pagamento sai. > [!WARNING] > > Só envie um pagamento para aprovação quando o veredito for `NONE`. Com `APPROVE`, o envio é recusado com `403 PIX_APPROVAL_NOT_REQUIRED` — confirme o pagamento em vez disso —, e com `DENY`, com `403 PIX_POLICY_DENIED`. ## Administradores da organização Um administrador da organização pode confirmar um pagamento **seja qual for a decisão das políticas**: a confirmação dele dispensa a aprovação e ainda devolve o veredito em `policy`, para registro. Clientes de API atuam como administradores das suas organizações, então isso também vale para eles. A única exceção é um pagamento que já está aguardando aprovação, que só a solicitação de aprovação dele pode resolver — um administrador a resolve forçando a aprovação ou a negação. ## Quando as políticas não podem ser avaliadas Se as políticas não puderem ser avaliadas naquele momento: * criar o pagamento e definir seus detalhes continuam funcionando, com `policy` igual a `{ "error": "POLICY_EVALUATION_UNAVAILABLE" }`; * enviar para aprovação e confirmar respondem `503 POLICY_EVALUATION_UNAVAILABLE` e não alteram nada — tente de novo em instantes. A confirmação de um administrador da organização segue adiante, com `policy: null`. ## Erros do fluxo | Status | `code` | Quando | O que fazer | | - | - | - | - | | `403` | `PIX_REQUIRES_APPROVAL` | Você confirmou um pagamento que uma política envia para aprovação. | Envie-o para aprovação. | | `403` | `PIX_POLICY_DENIED` | Uma política recusa o pagamento. | Ele não pode ser pago; cancele-o. | | `403` | `PIX_APPROVAL_NOT_REQUIRED` | Você enviou para aprovação um pagamento que as políticas aprovam. | Confirme-o. | | `403` | `PIX_PENDING_APPROVAL` | Você confirmou um pagamento que está aguardando aprovação. | Aguarde os aprovadores. | | `409` | `PIX_NOT_REQUESTABLE` | Você definiu os detalhes de um pagamento, ou o enviou para aprovação, quando ele já não estava `REQUESTED`. | Consulte o pagamento; crie um novo, se necessário. | | `409` | `PIX_STATUS_NOT_REQUESTED` | Você confirmou ou cancelou um pagamento que já estava confirmado, cancelado ou com falha. | Consulte o pagamento. | | `409` | `PIX_EXPIRED` | O prazo de aprovação passou; o pagamento agora está `EXPIRED`. | Crie um novo pagamento. | | `422` | `PAYMENT_PARAMETERS_MISSING` | O valor ou a categoria de saldo ainda não foi definido. | Defina os detalhes com `PUT`. | | `422` | `CUSTOM_FIELD_IS_REQUIRED` | Um campo personalizado obrigatório da transação está vazio. | Preencha-o com `PUT`. | | `503` | `POLICY_EVALUATION_UNAVAILABLE` | As políticas não puderam ser avaliadas. | Tente de novo em instantes. | ## Pagamentos de boleto Um [pagamento de boleto](https://developers.portao3.com.br/pt-BR/guides/pay-boleto.md) passa pelas mesmas etapas, nos seus próprios endpoints. Use o `_id` do pagamento como `{boletoId}`: | Etapa | Pix | Boleto | | - | - | - | | Criar o pagamento | [`POST .../pix`](https://developers.portao3.com.br/api-reference/banking/pix-payments/create-a-pix-payment) | [`POST .../boleto`](https://developers.portao3.com.br/api-reference/banking/boleto-payments/create-a-boleto-payment) | | Definir os detalhes | [`PUT .../pix/{pixId}`](https://developers.portao3.com.br/api-reference/banking/pix-payments/set-a-pix-payments-details) | [`PUT .../boleto/{boletoId}`](https://developers.portao3.com.br/api-reference/banking/boleto-payments/set-a-boleto-payments-details) | | Confirmar | [`POST .../pix/{pixId}/confirm`](https://developers.portao3.com.br/api-reference/banking/pix-payments/confirm-a-pix-payment) | [`POST .../boleto/{boletoId}/confirm`](https://developers.portao3.com.br/api-reference/banking/boleto-payments/confirm-a-boleto-payment) | | Enviar para aprovação | [`POST .../pix/{pixId}/request`](https://developers.portao3.com.br/api-reference/banking/pix-payments/send-a-pix-payment-for-approval) | [`POST .../boleto/{boletoId}/request`](https://developers.portao3.com.br/api-reference/banking/boleto-payments/send-a-boleto-payment-for-approval) | | Cancelar | [`POST .../pix/{pixId}/cancel`](https://developers.portao3.com.br/api-reference/banking/pix-payments/cancel-a-pix-payment) | [`POST .../boleto/{boletoId}/cancel`](https://developers.portao3.com.br/api-reference/banking/boleto-payments/cancel-a-boleto-payment) | | Consultar | [`GET .../pix/{pixId}`](https://developers.portao3.com.br/api-reference/banking/pix-payments/get-a-pix-payment) | [`GET .../boleto/{boletoId}`](https://developers.portao3.com.br/api-reference/banking/boleto-payments/get-a-boleto-payment) | O que muda para um boleto: * **O valor costuma ser conhecido depois da criação** — o `amount` que você enviou ou, se não enviou nenhum, o que o boleto cobra hoje (`txnUpdatedAmount`, ou o valor de face quando ele é `0`). Envie também `category` na criação e você pode ir direto para a etapa 3; caso contrário — ou quando o boleto não informa valor nenhum —, defina-os com `PUT`, que também permite mudar o valor, o dia ou os campos personalizados. * **Um boleto confirmado fica `PAID` na hora** — ele não passa por `CONFIRMED`. Quando uma solicitação de aprovação é aprovada, o pagamento passa a `PAID` (ou a `SCHEDULED`, se for para um dia futuro), ou a `FAILED`, se o banco o recusar. * **O que uma política enxerga**: `subjectType` é `BOLETO` — então uma política pode se aplicar só a pagamentos de boleto —, o beneficiário (`payee`, `payeeDocument`) é o destinatário (`creditParty`), quem consta como pagador no boleto é o `debitParty`, e `daysToDueDate` conta os dias até o vencimento do boleto. * **O dia do pagamento**: o prazo de aprovação é 21h (horário de São Paulo) do dia em que o pagamento será feito — hoje, a menos que você defina `scheduledAt`. Um boleto bancário só pode ser agendado para o vencimento (ou para o próximo dia útil, quando o vencimento cai em um fim de semana ou feriado; qualquer dia útil, quando ele não tem vencimento). * **Notificações**: assine o [webhook](https://developers.portao3.com.br/pt-BR/guides/webhooks.md) `BANK_SLIP_PAID`, enviado quando o boleto é pago. Os mesmos erros, com os códigos do boleto: | Status | `code` do Pix | `code` do boleto | | - | - | - | | `403` | `PIX_REQUIRES_APPROVAL` | `BOLETO_REQUIRES_APPROVAL` | | `403` | `PIX_POLICY_DENIED` | `BOLETO_POLICY_DENIED` | | `403` | `PIX_APPROVAL_NOT_REQUIRED` | `BOLETO_APPROVAL_NOT_REQUIRED` | | `403` | `PIX_PENDING_APPROVAL` | `BOLETO_PENDING_APPROVAL` | | `409` | `PIX_NOT_REQUESTABLE` | `BOLETO_NOT_REQUESTABLE` | | `409` | `PIX_STATUS_NOT_REQUESTED` | `INVALID_BANK_SLIP_STATE` | | `409` | `PIX_EXPIRED` | `BOLETO_EXPIRED` | | `422` | `PAYMENT_PARAMETERS_MISSING` | `PAYMENT_PARAMETERS_MISSING` | | `422` | `CUSTOM_FIELD_IS_REQUIRED` | `CUSTOM_FIELD_INVALID_VALUE` — é com este código que um boleto indica um campo personalizado obrigatório vazio | | `503` | `POLICY_EVALUATION_UNAVAILABLE` | `POLICY_EVALUATION_UNAVAILABLE` | ## Próximos passos > [card] [Enviar um pagamento Pix](https://developers.portao3.com.br/pt-BR/guides/send-pix.md) > > Pague por chave Pix, QR Code ou dados bancários, passo a passo. > [card] [Pagar um boleto](https://developers.portao3.com.br/pt-BR/guides/pay-boleto.md) > > Pague um boleto bancário ou uma conta de consumo pelo código de barras. > [card] [Receber webhooks](https://developers.portao3.com.br/pt-BR/guides/webhooks.md) > > Seja notificado quando um pagamento sair. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.