Skip to main content
POST
Report a Pix as a fraud
The transaction must be a Pix the wallet sent, with an end-to-end ID, and it can be reported only once. The report goes to the bank with situationType and reportDetails, and the answer is the infraction as recorded: direction SENT, status CREATED, with the bank’s references in external. From then on the bank keeps it up to date — status moves to OPEN, ACKNOWLEDGED and finally CLOSED (with the conclusion in analysisResult) or CANCELLED, and the two sides appear in reportParticipant and counterpartyParticipant. Follow it with GET .../transactions/{transactionId}/pix-infraction. Opening the report doesn’t move money: when the money is returned, it arrives as a Pix credited to the wallet. When the bank refuses the report — or refuses Portão 3’s sign-in to it — nothing is recorded and the answer carries the bank’s own HTTP status, with the code ERR_BAD_REQUEST (a 4xx) or ERR_BAD_RESPONSE (a 5xx) and, unless the bank gave a message, Request failed with status code and the status: the bank answers 422 when it doesn’t find the Pix. When the bank doesn’t answer at all, the answer is a 500 whose code is the system’s network error — ECONNABORTED when it took too long, ECONNREFUSED, ENOTFOUND, a certificate error such as CERT_HAS_EXPIRED, or another: that status’s code is not limited to the listed ones. After a 5xx, a dropped connection or a timeout, the bank may still have opened the report: it then shows up on the transaction once the bank updates it, so check GET .../transactions/{transactionId}/pix-infraction before sending it again. Use default as walletId for the organization’s main wallet. Only Portão 3’s own services and back office can open a Pix infraction report.

Headers

x-environment
enum<string>

Environment of the transaction: LIVE (production) or TEST (sandbox). When you omit it, TEST is used; any other value is rejected.

Available options:
LIVE,
TEST

Path Parameters

realmId
string<uuid>
required

ID of the realm.

Format: UUID

organizationId
string<uuid>
required

ID of the organization.

Format: UUID

accountId
string
required

ID of the organization's account (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$
walletId
string
required

ID of the wallet that sent the Pix (24 hexadecimal characters), or default for the organization's main wallet.

Pattern: ^([0-9a-fA-F]{24}|default)$
transactionId
string
required

ID of the outgoing Pix in the wallet's statement — the transaction's _id (24 hexadecimal characters).

Pattern: ^[0-9a-fA-F]{24}$

Body

application/json
reason
enum<string>
required

Why the report is opened: send REFUND_REQUEST — it asks for the money back. REFUND_CANCELLED is accepted too but cancels nothing. Either is kept on the infraction until the bank's first update, which sets the reason itself (REFUND_CANCELLED once the report is cancelled).

Available options:
REFUND_REQUEST,
REFUND_CANCELLED
Example:

"REFUND_REQUEST"

situationType
enum<string>
required

What happened: SCAM — the payer was deceived into paying; ACCOUNT_TAKEOVER — someone took over the payer's account; COERCION — the payer was forced to pay; FRAUDULENT_ACCESS — someone used the payer's account without permission; OTHER — anything else. UNKNOWN is reported as OTHER.

Available options:
SCAM,
ACCOUNT_TAKEOVER,
COERCION,
FRAUDULENT_ACCESS,
OTHER,
UNKNOWN
Example:

"SCAM"

reportDetails
string
required

What happened, in your words — 1 to 2,000 characters. It goes with the report to the institution that received the Pix.

Required string length: 1 - 2000
Example:

"A cliente pagou um falso fornecedor que se passou pela Gráfica Aurora. O recebedor não entregou nada e não responde."

Response

Successful response

A Pix infraction report (MED — the Central Bank's special refund mechanism): a claim that a Pix was a fraud, opened by the payer's institution against the receiver's so the money can be blocked and returned. direction says which side the wallet is on.

_id
string
required

ID of the infraction (24 hexadecimal characters).

Example:

"6728e0a4b4d3e80012c9a6b1"

environment
enum<string>
required

Environment of the infraction: LIVE (production) or TEST (sandbox).

Available options:
LIVE,
TEST
Example:

"LIVE"

realmId
string
required

ID of the realm.

Example:

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

organizationId
string
required

ID of the organization.

Example:

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

accountId
string
required

ID of the organization's account.

Example:

"66f2a1c7b4d3e80012c9a0b4"

walletId
string
required

ID of the wallet that sent or received the Pix.

Example:

"66f2a3d1b4d3e80012c9a0d2"

transactionId
string
required

ID of the Pix transaction in the wallet's statement.

Example:

"6726b1c2b4d3e80012c9a4f7"

direction
enum<string>
required

Which side the wallet is on: RECEIVED — another institution reported a Pix the wallet received (the payer says it was a fraud); SENT — Portão 3 reported a Pix the wallet sent, at the organization's request.

Available options:
SENT,
RECEIVED
Example:

"SENT"

reason
enum<string>
required

REFUND_REQUEST — the report asks for the money back; REFUND_CANCELLED — the bank marked the request as cancelled. On a report Portão 3 just opened, until the bank's first update, it is the value sent with it, and cancels nothing. Some older cancelled reports still say REFUND_REQUEST. Read status to know whether a report was cancelled.

Available options:
REFUND_REQUEST,
REFUND_CANCELLED
Example:

"REFUND_REQUEST"

situationType
enum<string>
required

What the report says happened: SCAM — the payer was deceived into paying; ACCOUNT_TAKEOVER — someone took over the payer's account; COERCION — the payer was forced to pay; FRAUDULENT_ACCESS — someone used the payer's account without permission; OTHER — anything else, or not stated. UNKNOWN appears only on a report you just opened with it, until the bank's first update (it is reported as OTHER).

Available options:
SCAM,
ACCOUNT_TAKEOVER,
COERCION,
FRAUDULENT_ACCESS,
OTHER,
UNKNOWN
Example:

"SCAM"

reportDetails
string | null
required

What happened, in the reporter's words. Empty or null on some older reports.

Example:

"A cliente pagou um falso fornecedor que se passou pela Gráfica Aurora. O recebedor não entregou nada e não responde."

external
object
required

References of the report at the bank.

status
enum<string>
required

Where the report stands: CREATED — just opened by Portão 3, until the bank's first update; OPEN — opened, waiting for the receiver's institution; ACKNOWLEDGED — the receiver's institution is analyzing it; CLOSED — the analysis is over (see analysisResult); CANCELLED — the report was withdrawn. CLOSED and CANCELLED are final.

Available options:
OPEN,
ACKNOWLEDGED,
CLOSED,
CANCELLED,
CREATED
Example:

"CREATED"

analysisResult
enum<string>
required

The receiver's institution's conclusion: AGREED — it agrees the Pix was a fraud; DISAGREED — it doesn't; PENDING — no conclusion recorded. Final only once status is CLOSED: on a report you received it can already say AGREED while the report is OPEN or ACKNOWLEDGED.

Available options:
AGREED,
DISAGREED,
PENDING
Example:

"PENDING"

analysisDetails
string
required

Notes of the analysis, when the receiver's institution wrote any. Empty otherwise.

Example:

""

effectiveAt
string
required

When the report was opened at the bank (ISO 8601, UTC). Not always the bank's time: on a report Portão 3 just opened (until the bank's first update) and on the records written when a wallet is blocked for fraud, it is when the record was written — on some older ones, a moment before it.

Example:

"2026-11-04T14:02:37.115Z"

changedAt
string
required

When the report's last change was recorded (ISO 8601, UTC). On a few older reports that never recorded one, the time of your request.

Example:

"2026-11-04T14:02:37.115Z"

createdAt
string<date-time>
required

When the infraction was recorded (ISO 8601, UTC).

Example:

"2026-11-04T14:02:37.120Z"

updatedAt
string<date-time>
required

When the infraction was last updated (ISO 8601, UTC).

Example:

"2026-11-04T14:02:37.120Z"

__v
number
required

Internal version of the record.

Example:

0

endToEndId
string

End-to-end ID of the Pix (32 characters). Absent or empty on a few older reports.

Example:

"E12345678202611031022p9Q8r7S6t5U"

reportParticipant
object

The side that opened the report (the payer's).

counterpartyParticipant
object

The side the report is against (the receiver's).