Políticas de negócio e aprovações

​

O que uma política decide

​

O fluxo

​

Etapa 1: Criar o pagamento

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix' \
  -H 'Authorization: Bearer <accessToken>' \
  -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"
  }'

{
  "_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" }]
    }
  }
}

​

Etapa 2: Definir os detalhes e ler o veredito

curl -X PUT \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 123000,
    "category": "FLEX_INTERNATIONAL",
    "customFields": { "cost-center": "CC-1020" }
  }'

​

Etapa 3a: Confirmar o pagamento

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}/confirm' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

​

Etapa 3b: Enviar o pagamento para aprovação

curl -X POST \
  'https://api.banking.v2.portao3.com.br/realms/{realmId}/organizations/{organizationId}/accounts/{accountId}/wallets/{walletId}/pix/{pixId}/request' \
  -H 'Authorization: Bearer <accessToken>' \
  -H 'x-environment: LIVE'

{
  "_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": [] }
    ]
  }
}

• 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 — 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 ou negar 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 ou forçar a negação.
• 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.

​

Administradores da organização

​

Quando as políticas não podem ser avaliadas

• 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

​

Pagamentos de 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 BANK_SLIP_PAID, enviado quando o boleto é pago.

​

Próximos passos