Policies and Rules

The policy system allows configuring security rules, limits, and restrictions for PIX operations. Rules are evaluated automatically on each transaction and can block, refund, or notify about violations.

Configuration Hierarchy

Policies follow a three-level hierarchy:

Default (base) -> Tenant (overrides default) -> Account (overrides tenant)

Each level can define specific rules. Values not set at a level are inherited from the level above. This allows having global rules at the default level with per-tenant or per-account adjustments.

PIX Out Rules (Outgoing Transfers)

Rules are evaluated in the order below. The first violation found stops evaluation.

Order	Rule	Description	Action
1	Kill Switch	Disables all outgoing transfers	REJECT
2	Operating Hours	Restricts operations to a time window	REJECT
3	Whitelist	If the payee is whitelisted, allows and skips all rules below	ALLOW
4	Blacklist	Blocks if the payee is blacklisted	REJECT
5	Same Ownership	Only allows transfers to the same CPF/CNPJ	REJECT
6	Transaction Limit	Maximum amount per transfer	REJECT
7	Night Limit	Reduced maximum between 20:00-06:00 (BRT)	REJECT
8	Person Type	Restricts by payee type (PF/PJ)	REJECT
9	Approval	Above a threshold, requires manual approval	HOLD_FOR_APPROVAL

PIX In Rules (Incoming Transfers)

For incoming transfers, all violations use the same configurable action (violationAction).

Order	Rule	Description
1	Whitelist	If the payer is whitelisted, allows and skips all rules below
2	Blacklist (Document)	Blocks if the payer is in the CPF/CNPJ blacklist
3	Blacklist (Bank)	Blocks if the originating bank is blacklisted
4	Same Ownership	Only accepts PIX from the same CPF/CNPJ
5	Amount Limit	Maximum amount per incoming transaction
6	Person Type	Restricts by payer type (PF/PJ)
7	Allowed Banks	Only accepts PIX from specific banks

Violation Actions (PIX In)

When a PIX In rule is violated, the configured action is applied:

Action	Description
ALLOW_AND_NOTIFY	Allows the transaction but records the violation (default)
AUTO_REFUND	Automatically refunds the amount to the payer
QUARANTINE	Places the transaction in quarantine for N days
BLOCK	Locks the balance corresponding to the transaction

QR Code Rules

Rule	Description
Dynamic QR	Enable/disable dynamic QR code creation
Static QR	Enable/disable static QR code creation
Max Amount	Amount limit per QR code
Min Amount	Minimum amount per QR code

PIX Key Rules

Rule	Description
Creation	Enable/disable PIX key creation
Max Keys	Maximum number of keys per account

Refund Rules

Rule	Description
Enabled	Enable/disable refunds
Max Amount	Amount limit per refund

MED (Dispute) Rules

Rule	Description
Auto-block	Automatically lock balance for MEDs above a specified amount
Max Rate	Limit for the MED/PIX-In ratio
Action	What to do when the rate is exceeded: NOTIFY, BLOCK PIX IN, BLOCK PIX OUT, BLOCK ALL

Operating Hours

Restricts all operations to a time window. Supports overnight windows (e.g., 22:00-06:00).

Field	Description	Example
start	Start time	06:00
end	End time	22:00
timezone	Timezone	America/Sao_Paulo

The Whitelist Principle

In both PIX Out and PIX In, the whitelist is evaluated first. If the payer/payee document (CPF/CNPJ) is in the whitelist, all other rules are skipped and the transaction is allowed.

This allows creating exceptions for trusted partners that should not be affected by limits, blacklists, or other restrictions.

Violation Visibility

All policy violations are recorded on the transaction and visible:

• In the statement (GET /v1/accounts/{accountId}/statement), in the policyViolations and violationAction fields
• Via policy.violation webhook (when configured)
• In the admin panel (Backoffice)

See the Disputes (MED) guide for details on MED-specific rules.