# Pix Infraction

A Pix Infraction is used to respond to Pix fraud and operational issues to the Brazilian Central Bank.

Here we will show you how to manage them.

### The Pix Infraction Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix infraction. |
| `referenceId` | STRING | End-to-end id of the transaction the infraction refers to. |
| `type` | STRING | Type of infraction. Options: "reversal", "reversalChargeback". |
| `method` | STRING | Fraud method. Options: "scam", "invasion", "other", "unauthorized", "coercion", "unknown". |
| `operatorEmail` | STRING | Contact email of the operator responsible for the Pix infraction. |
| `operatorPhone` | STRING | Contact phone number of the operator responsible for the Pix infraction. |
| `fraudId` | STRING | Id of the Pix fraud marking associated with the infraction. |
| `fraudType` | STRING | Type of fraud associated with the infraction. Options: "identity", "mule", "scam", "other", "unknown". |
| `description` | STRING | Description of the infraction. |
| `analysis` | STRING | Analysis text that justifies the result of the infraction report. |
| `tags` | LIST OF STRINGS | Tags associated with the Pix infraction. |
| `bacenId` | STRING | Id of the infraction at the Brazilian Central Bank. |
| `disputeId` | STRING | Id of the Pix dispute associated with the infraction. |
| `amount` | INTEGER | Amount in cents related to the infraction. Example: 1234 (= R$ 12.34). |
| `flow` | STRING | Direction of the infraction report. Options: "out" (reported by you), "in" (reported against you). |
| `status` | STRING | Current status. Options: "created", "failed", "delivered", "closed", "canceled". |
| `creditedBankCode` | STRING | Bank ISPB code of the credited party. |
| `debitedBankCode` | STRING | Bank ISPB code of the debited party. |
| `reportedBy` | STRING | Institution that reported the infraction. Options: "debited", "credited". |
| `result` | STRING | Result of the infraction analysis. Options: "agreed", "disagreed". |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### List Pix Infractions

`GET /v2/pix-infraction`

List and filter all Pix infractions. Results are paged.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter by status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `type` | OPTIONAL | Filter by infraction type. |

**Request**

```python
import starkinfra

infractions = starkinfra.pixinfraction.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["delivered"],
    type=["fraud"],
    flow="out",
    tags=["infraction", "fraud"]
)

for infraction in infractions:
    print(infraction)
```

**Response**

```python
<generator object query at 0x...>

PixInfraction(
    id="5656565656565656",
    reference_id="E20018183202201060100rq1feOMJqtZ",
    type="fraud",
    method="scam",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    fraud_id="5741774970552320",
    fraud_type="scam",
    description="Client reported unauthorized transaction.",
    analysis="Fraud confirmed after investigation.",
    tags=["infraction", "fraud"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="4545454545454545",
    amount=1234,
    flow="out",
    status="delivered",
    credited_bank_code="20018183",
    debited_bank_code="20018183",
    reported_by="credited",
    result="agreed",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Infraction

`GET /v2/pix-infraction/:id`

Get a single Pix infraction by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix infraction entity. |

**Request**

```python
import starkinfra

infraction = starkinfra.pixinfraction.get("5656565656565656")

print(infraction)
```

**Response**

```python
PixInfraction(
    id="5656565656565656",
    reference_id="E20018183202201060100rq1feOMJqtZ",
    type="fraud",
    method="scam",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    fraud_id="5741774970552320",
    fraud_type="scam",
    description="Client reported unauthorized transaction.",
    analysis="Fraud confirmed after investigation.",
    tags=["infraction", "fraud"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="4545454545454545",
    amount=1234,
    flow="out",
    status="delivered",
    credited_bank_code="20018183",
    debited_bank_code="20018183",
    reported_by="credited",
    result="agreed",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Update a Pix Infraction

`PATCH /v2/pix-infraction/:id`

Respond to an incoming Pix infraction report.

Agree with an inbound infraction by patching its analysis to agreed, or disagree by patching it to disagreed.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix infraction entity. |
| `result` | REQUIRED | Result of the analysis. Options: "agreed", "disagreed". |
| `fraudType` | CONDITIONALLY REQUIRED | Type of fraud associated with the infraction. Required when result is "agreed", optional when result is "disagreed". Options: "identity", "mule", "scam", "other". |
| `analysis` | OPTIONAL | Analysis text explaining the result. |

**Request**

```python
import starkinfra

infraction = starkinfra.pixinfraction.update(
    "5656565656565656",
    result="agreed",
    fraud_type="scam",
    analysis="Fraud confirmed after investigation."
)

print(infraction)
```

**Response**

```python
PixInfraction(
    id="5656565656565656",
    reference_id="E20018183202201060100rq1feOMJqtZ",
    type="fraud",
    method="scam",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    fraud_id="5741774970552320",
    fraud_type="scam",
    description="Client reported unauthorized transaction.",
    analysis="Fraud confirmed after investigation.",
    tags=["infraction", "fraud"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="4545454545454545",
    amount=1234,
    flow="in",
    status="closed",
    credited_bank_code="20018183",
    debited_bank_code="20018183",
    reported_by="debited",
    result="agreed",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:02:00+00:00"
)
```

### Cancel a Pix Infraction

`DELETE /v2/pix-infraction/:id`

Cancel a Pix infraction you reported.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix infraction entity. |

**Request**

```python
import starkinfra

infraction = starkinfra.pixinfraction.cancel("5656565656565656")

print(infraction)
```

**Response**

```python
PixInfraction(
    id="5656565656565656",
    reference_id="E20018183202201060100rq1feOMJqtZ",
    type="fraud",
    method="scam",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    fraud_id="5741774970552320",
    fraud_type="scam",
    description="Client reported unauthorized transaction.",
    analysis="Fraud confirmed after investigation.",
    tags=["infraction", "fraud"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="4545454545454545",
    amount=1234,
    flow="out",
    status="canceled",
    credited_bank_code="20018183",
    debited_bank_code="20018183",
    reported_by="credited",
    result="agreed",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:03:00+00:00"
)
```

### List Pix Infraction Logs

`GET /v2/pix-infraction/log`

Get a paged list of all Pix infraction logs.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. |
| `ids` | OPTIONAL | Filter by Pix infraction ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filter logs by log types. |

**Request**

```python
import starkinfra

logs = starkinfra.pixinfraction.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    types=["delivered"]
)

for log in logs:
    print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    infraction=PixInfraction(
        id="5656565656565656",
        reference_id="E20018183202201060100rq1feOMJqtZ",
        type="fraud",
        method="scam",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        fraud_id="5741774970552320",
        fraud_type="scam",
        description="Client reported unauthorized transaction.",
        analysis="Fraud confirmed after investigation.",
        tags=["infraction", "fraud"],
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        dispute_id="4545454545454545",
        amount=1234,
        flow="out",
        status="delivered",
        credited_bank_code="20018183",
        debited_bank_code="20018183",
        reported_by="credited",
        result="agreed",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    type="delivered",
    errors=[],
    created="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Infraction Log

`GET /v2/pix-infraction/log/:id`

Get a single Pix infraction log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the log entity. |

**Request**

```python
import starkinfra

log = starkinfra.pixinfraction.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    infraction=PixInfraction(
        id="5656565656565656",
        reference_id="E20018183202201060100rq1feOMJqtZ",
        type="fraud",
        method="scam",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        fraud_id="5741774970552320",
        fraud_type="scam",
        description="Client reported unauthorized transaction.",
        analysis="Fraud confirmed after investigation.",
        tags=["infraction", "fraud"],
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        dispute_id="4545454545454545",
        amount=1234,
        flow="out",
        status="delivered",
        credited_bank_code="20018183",
        debited_bank_code="20018183",
        reported_by="credited",
        result="agreed",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    type="delivered",
    errors=[],
    created="2022-01-01T00:01:00+00:00"
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkinfra.com/api/v2/pix-infraction-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/pix-infraction-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/pix-infraction-php.md)
- [Java](https://docs.starkinfra.com/api/v2/pix-infraction-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/pix-infraction-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/pix-infraction-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/pix-infraction-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/pix-infraction-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/pix-infraction-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/pix-infraction-curl.md)