Skip to main content
POST
Deny a policy request
You can deny while one of the request’s open (REQUESTED) approval steps names you — as the user, or as a member of the group. One denial is final: the request becomes DENIED and every other open step CANCELED. Portão 3 then cancels its subject — the payment or transfer request is cancelled, the spend review declined. If that step fails, the request still ends DENIED and nothing retries it: read the subject to confirm its status. Send an optional reason: it is kept as the request’s denialReason and on your approval step, and shown to the requester. A repeated deny changes nothing: it answers the request as it is, or 409 POLICY_REQUEST_ALREADY_RESOLVED when your denial also closed another step that named you. If approvalDeadline passed while a step was still waiting for a decision, acting on the request expires it instead: it becomes EXPIRED, Portão 3 cancels its subject, and the answer is 403 POLICY_REQUEST_EXPIRED.

Path Parameters

realmId
string<uuid>
required

ID of your realm.

Format: UUID

organizationId
string<uuid>
required

ID of the organization the policy request belongs to.

Format: UUID

policyRequestId
string<uuid>
required

ID of the policy request. A payment or transfer request sent for approval carries it as policyRequestId.

Format: UUID

Body

application/json
reason
string

Why you decided this way, shown to the requester. Optional; surrounding spaces are removed, and a blank reason is refused.

Required string length: 1 - 500
Example:

"Fora do orçamento do trimestre"

Response

Successful response

A policy request: the approval request of a payment, a transfer request or a reviewed transaction, waiting for the decisions a business policy requires.

id
string<uuid>
required

ID of the policy request.

Example:

"4d2c1b0a-9f8e-4d7c-8b6a-5f4e3d2c1b0a"

realmId
string<uuid>
required

ID of the realm the request belongs to.

Example:

"f495ff0c-ab54-4f99-8e92-ca8682e4de9b"

organizationId
string<uuid>
required

ID of the organization the request belongs to.

Example:

"c4bd3f21-dfbd-44e8-8055-68ba15bed410"

accountId
string
required

ID of the account that holds walletId.

Example:

"66f2a1c7b4d3e80012c9a0b4"

walletId
string
required

ID of the subject's wallet — the paying wallet of a payment, the transaction's wallet in a spend review.

Example:

"6710b8e4c9e77b0012a4d6f3"

context
enum<string>
required

Which policies govern the subject: PAYMENT, SPEND_REVIEW or TRAVEL.

Available options:
PAYMENT,
SPEND_REVIEW,
TRAVEL
Example:

"PAYMENT"

subjectType
string
required

What is being approved: PIX, BOLETO, WALLET_TRANSFER_REQUEST (a transfer request between wallets) or TRANSACTION (a spend review).

Example:

"PIX"

subjectId
string
required

ID of the subject — the payment's _id, the transfer request's or the transaction's ID.

Example:

"6726a4f1b4d3e80012c9a3f1"

requester
object
required

Who asked for the subject.

body
object
required

The subject as it was when the request was opened — what the policies evaluated and what the approvers are approving. A payment's approved amount and balance category are in confirmation.


Example: {"amount":123000,"description":"Folders da campanha de novembro","creditParty":{"name":"Gráfica Aurora Ltda"},"confirmation":{"amount":123000,"category":"FLEX_INTERNATIONAL"}}

Example:
policyId
string<uuid>
required

ID of the business policy that required the approval.

Example:

"3f2e1d0c-9b8a-4c7d-8e6f-5a4b3c2d1e0f"

status
enum<string>
required

Status of the request. REQUESTED — waiting for decisions. APPROVED — every required approval was given (or an admin force-approved it). DENIED — an approver or an admin denied it. CANCELED — the requester, an admin or Portão 3 cancelled it. EXPIRED — approvalDeadline passed while it was waiting. Every status but REQUESTED is final.

Available options:
REQUESTED,
APPROVED,
DENIED,
CANCELED,
EXPIRED
Example:

"DENIED"

executionStatus
enum<string>
required

What happens after the approval: the policy's top-up, if any, then the subject is carried out (the payment is confirmed, the transfer request confirmed, the spend review approved). WAITING — not started: a request that is not approved stays WAITING, and an approved one goes back to it while a temporary problem is retried. PROCESSING — running. EXECUTED — done. FAILED — stopped, with the reason in executionFailReason.

Available options:
WAITING,
PROCESSING,
EXECUTED,
FAILED
Example:

"WAITING"

approvalDeadline
string<date-time>
required

When the request expires if it is still waiting for decisions. Set by whoever opened the request — for a Pix or boleto payment, 21:00 (São Paulo time) of the day the payment is for, and at least one hour after it was sent.

Example:

"2026-11-07T00:00:00.000Z"

approvalHierarchy
boolean
required

true — the approval steps open one at a time, in order. false — they are all open at once.

Example:

false

approvals
object[]
required

The approval steps, in the policy's order. Empty on an AUTO request.

createdAt
string<date-time>
required

When the request was opened.

Example:

"2026-11-06T13:42:10.512Z"

updatedAt
string<date-time>
required

When the request last changed.

Example:

"2026-11-06T13:42:10.512Z"

walletName
string

Name of the wallet when the request was opened. Absent on older requests.

Example:

"Marketing"

cardName
string

Name of the card, for a reviewed card transaction. Absent otherwise.

Example:

"Cartão Marketing"

denialReason
string

The reason given by whoever denied the request. Only on a DENIED request, and only when a reason was given.

Example:

"Fora do orçamento do trimestre"

resolution
enum<string>

AUTO when the policy approves on its own: the request was created already APPROVED, with no approvers, to run the policy's top-up. Absent on a request that went through approvers.

Available options:
AUTO
Example:

"AUTO"

executionMode
enum<string>

MOVE_BALANCE_ONLY when only the policy's top-up runs after the approval and the subject is carried out separately. Absent otherwise.

Available options:
MOVE_BALANCE_ONLY
Example:

"MOVE_BALANCE_ONLY"

executionFailReason
string

Why the execution failed, or why it is being retried — a code such as MOVE_BALANCE_SOURCE_MISSING for a problem detected before any money moved, otherwise the error of the step that failed (up to 200 characters).

Example:

"MOVE_BALANCE_SOURCE_MISSING"

executionMoveBalance
object

The top-up the matched policy runs after the approval. Absent when it has none.

fundingClaimedAt
string<date-time>

When this request took charge of topping up the subject's wallet — just before the top-up ran. Only on the one request per subject that does it.

Example:

"2026-11-06T15:03:45.031Z"

fundedAt
string<date-time>

When the top-up for this subject completed. Absent while it has not completed, or when this request moved no money.

Example:

"2026-11-06T15:03:46.418Z"

fundingClaim
boolean

true on the one request per subject that took charge of topping up its wallet. It is set before the top-up runs and kept even if the top-up then fails, so it does not mean the money moved — fundedAt does. Absent otherwise.

Example:

true

executionAttempts
number

How many times the execution was retried after a temporary problem that happened before any money moved. Absent when it was never retried.

Example:

1