Skip to main content
An organization’s admins write business policies — rules such as “Pix payments above R$ 1,000 need the finance team’s approval” or “no payments from the Marketing wallet on weekends”. Every Pix and boleto payment made from the organization’s wallets is checked against them, and the matching policy decides what happens to it. This guide shows how to read that decision and act on it: create the payment, set its details, then either confirm it straight away or send it for approval.
The steps below use a Pix payment. Boleto payments follow the same policies and the same create → set details → send for approval or confirm flow, through their own endpoints and with their own error codes — see Boleto payments.Transfer requests between wallets are checked against the same policies and go through the same send for approval or confirm steps, with their own endpoints and error codes. The main differences: their amount and balance category are fixed when they are created — to change them, cancel the request and create a new one — and only organization admins can cancel them.

​
What a policy decides

The organization’s policies are evaluated in their order, and the first one whose conditions match the payment decides. Conditions read the payment as it stands: its amount, the balance category it is charged to, the recipient, the paying wallet, who created it, its custom fields, and how many days are left to its due date. The decision is the policy’s actions.autoAction: A policy can also top up the wallet before paying (actions.moveBalance): the payment’s amount is first moved into the paying wallet from another one, then paid. That happens on its own when a payment the policy approves is confirmed, and when an approval request is approved — you don’t do anything extra. An organization admin who confirms a payment the policy would send for approval, or refuse, gets no top-up. A payment for a later day (scheduledAt) that you confirm directly is not topped up — make sure the wallet has the money on that day; one that goes through an approval is topped up when it is approved. Admins manage the policies in the Portão 3 app or through the Rule Engine API’s business policies endpoints.

​
The flow

Every step answers with the payment, so you always know its status.

​
Step 1: Create the payment

Create the Pix payment with the recipient — a Pix key, a Pix Copia e Cola / QR code, or bank details. Nothing is paid yet: the payment starts as REQUESTED.
The answer brings the payment and policy — what the policies say about it as it stands:
Use _id as {pixId} in the next steps.

​
Step 2: Set the details and read the verdict

pendingConfirmation holds what will be paid — the amount, the balance category charged and a description. Sending for approval and confirming take no details of their own: they use these. When you sent amount and category at creation (as above), they are already set and policy already reflects them — go to step 3. Otherwise — typically a QR code, whose amount you only know after reading it, or a create without category — set the details:
The answer brings the updated payment and a fresh policy. Read policy.actions.autoAction from the latest answer to choose step 3a, 3b or nothing (DENY). You can call PUT as many times as you need while the payment is REQUESTED.
Unless the QR code has an open amount (txnAllowAmountChange: true), amount must be the payment’s txnUpdatedAmount (a COBV charge scheduled for its due date may also pay its txnOriginalAmount). Fill in every required transaction custom field here too — confirming and sending for approval refuse a payment that misses one.

​
Step 3a: Confirm the payment

When the verdict is APPROVE, confirm the payment. Send no body:
The policies are evaluated once more, with the stored details. If they still approve, the money moves: the answer is 200 with the payment CONFIRMED — it becomes PAID when the Pix network settles it. If the payment is for a later day (scheduledAt), the answer is 201 with the schedule instead, and the payment becomes SCHEDULED. If a policy now requires approval, the confirmation is refused with 403 PIX_REQUIRES_APPROVAL — send the payment for approval instead. If a policy refuses it, you get 403 PIX_POLICY_DENIED.

​
Step 3b: Send the payment for approval

When the verdict is NONE, send the payment for approval. Send no body:
The payment becomes PENDING_APPROVAL, and an approval request is opened for the approvers the policy names. The answer brings it in policyRequest:
From here:
  • The details are frozen. The approvers approve exactly the amount, category and description the payment had when it was sent. To change them, cancel the payment — its approval request is cancelled too — and create a new one.
  • The approvers decide. They are notified in the Portão 3 app and approve or deny there, or through the Rule Engine API — approve or deny the approval request whose id is the payment’s policyRequestId. With approvalHierarchy: true they decide one after the other, in order. Organization admins can decide any request on their own: force-approve or force-deny.
  • Approved → paid. Once every approval is given, Portão 3 confirms the payment for you, with the approved details — no call from you. It becomes CONFIRMED, then PAID (or SCHEDULED, for a later day). If the payment is refused at that point — for example, for insufficient funds — it becomes FAILED, with the reason in failReason.
  • Approved, but not carried out. If the policy’s top-up of the wallet can’t be done after the approval, the payment is not sent. A few problems found before any money moves are retried automatically (the approval request’s executionStatus goes back to WAITING). Any other failure — a timeout or an error from the bank during the top-up included — ends the approval request with executionStatus: FAILED and the reason in executionFailReason, and the payment stays PENDING_APPROVAL until its deadline, then shows as EXPIRED. The top-up may have gone through: check the wallets’ balances before you cancel the payment and create a new one, and contact support if the money moved.
  • Denied → cancelled. The payment becomes CANCELLED.
  • Deadline passed → expired. The deadline is approvalExpiresAt: 21:00 (São Paulo time) of the day the payment is for, and at least one hour after it was sent. A payment still waiting then becomes EXPIRED.
While it waits, the payment can’t be confirmed by hand — not even by an organization admin (403 PIX_PENDING_APPROVAL): the approval request is the record of the decision. To follow the outcome, read the payment until its status leaves PENDING_APPROVAL, read the approval request to see who decided what, or subscribe to the PIX_OUT webhook, sent when the payment goes out.
Only send a payment for approval when the verdict is NONE. With APPROVE the request is refused with 403 PIX_APPROVAL_NOT_REQUIRED — confirm it instead — and with DENY, with 403 PIX_POLICY_DENIED.

​
Organization admins

An organization admin can confirm a payment whatever the policies decide: their confirmation skips the approval and still returns the verdict in policy, for the record. API clients act as admins of their organizations, so this applies to them too. The only exception is a payment already waiting for approval, which only its approval request can resolve — an admin settles it with force-approve or force-deny.

​
When the policies can’t be evaluated

If the policies can’t be evaluated at that moment:
  • creating the payment and setting its details still succeed, with policy set to { "error": "POLICY_EVALUATION_UNAVAILABLE" };
  • sending for approval and confirming answer 503 POLICY_EVALUATION_UNAVAILABLE and change nothing — retry shortly. An organization admin’s confirmation goes ahead, with policy: null.

​
Errors of the flow

​
Boleto payments

A boleto payment goes through the same steps, on its own endpoints. Use the payment’s _id as {boletoId}: What differs for a boleto:
  • The amount is usually known after creating — the amount you sent, or else what the boleto asks for today (txnUpdatedAmount, or its face value when that is 0). Send category at creation too and you can go straight to step 3; otherwise — or when the boleto states no amount at all — set them with PUT, which also lets you change the amount, the day or the custom fields.
  • A confirmed boleto is PAID right away — there is no CONFIRMED step. Once an approval request is approved, the payment becomes PAID (or SCHEDULED, for a later day), or FAILED if the bank refuses it.
  • What a policy sees: subjectType is BOLETO — so a policy can govern boleto payments only — the beneficiary (payee, payeeDocument) is the recipient (creditParty), who the boleto was issued to is debitParty, and daysToDueDate counts the days to the boleto’s due date.
  • The day to pay: the approval deadline is 21:00 (São Paulo time) of the day the payment is for — today, unless you set scheduledAt. A bank boleto can only be scheduled for its due date (or the next business day, when it falls on a weekend or holiday; any business day when it has no due date).
  • Notifications: subscribe to the BANK_SLIP_PAID webhook, sent when the boleto is paid.
The same errors, with the boleto’s codes:

​
Next steps

Send a Pix payment

Pay by Pix key, QR code or bank details, step by step.

Pay a boleto

Pay a bank boleto or a utility bill from its barcode.

Receive webhooks

Get notified when a payment goes out.