# Pix Fraud

A Pix Fraud report allows you to flag suspicious users or keys in the Brazilian Pix system (DICT).

Here we will show you how to create and manage them.

### The Pix Fraud Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix fraud report. |
| `externalId` | STRING | Unique external ID to prevent duplicates. |
| `type` | STRING | Type of fraud. Options: "identity", "mule", "scam", "other", "unknown". |
| `taxId` | STRING | CPF or CNPJ of the fraudster. |
| `keyId` | STRING | Pix key associated with the fraud. |
| `bacenId` | STRING | Central Bank ID for this fraud report. |
| `status` | STRING | Current status. Options: "created", "failed", "registered", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix fraud report. |
| `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". |

### Create Pix Fraud Reports

`POST /v2/pix-fraud`

Report a fraudulent user or Pix key to DICT.

You can create up to 100 fraud reports in a single request.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `externalId` | REQUIRED | Unique string to prevent duplicates. |
| `type` | REQUIRED | Type of fraud. Options: "identity", "mule", "scam", "other". |
| `taxId` | REQUIRED | CPF or CNPJ of the fraudster. |
| `keyId` | OPTIONAL | Pix key associated with the fraud. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |

**Request**

```python
import starkinfra

frauds = starkinfra.pixfraud.create([
    starkinfra.PixFraud(
        external_id="my-fraud-id-1",
        type="mule",
        tax_id="012.345.678-90",
        key_id="jon.snow@starkinfra.com",
        tags=["fraud", "mule"]
    )
])

for fraud in frauds:
    print(fraud)
```

**Response**

```python
[
    PixFraud(
        id="5656565656565656",
        external_id="my-fraud-id-1",
        type="mule",
        tax_id="012.345.678-90",
        key_id="jon.snow@starkinfra.com",
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        status="created",
        tags=["fraud", "mule"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Fraud Reports

`GET /v2/pix-fraud`

List and filter all Pix fraud reports. Results are paged.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `bacenId` | OPTIONAL | Filter by the Central Bank ID of the fraud report. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `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 fraud type. Options: "identity", "mule", "scam", "other". |

**Request**

```python
import starkinfra

frauds = starkinfra.pixfraud.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["registered"],
    type=["mule"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    tags=["fraud", "mule"]
)

for fraud in frauds:
    print(fraud)
```

**Response**

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

PixFraud(
    id="5656565656565656",
    external_id="my-fraud-id-1",
    type="mule",
    tax_id="012.345.678-90",
    key_id="jon.snow@starkinfra.com",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    status="registered",
    tags=["fraud", "mule"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Fraud Report

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

Get a single Pix fraud report by its id.

**Parameters**

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

**Request**

```python
import starkinfra

fraud = starkinfra.pixfraud.get("5656565656565656")

print(fraud)
```

**Response**

```python
PixFraud(
    id="5656565656565656",
    external_id="my-fraud-id-1",
    type="mule",
    tax_id="012.345.678-90",
    key_id="jon.snow@starkinfra.com",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    status="registered",
    tags=["fraud", "mule"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:01:00+00:00"
)
```

### Cancel a Pix Fraud Report

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

Cancel a Pix fraud report you submitted.

**Parameters**

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

**Request**

```python
import starkinfra

fraud = starkinfra.pixfraud.cancel("5656565656565656")

print(fraud)
```

**Response**

```python
PixFraud(
    id="5656565656565656",
    external_id="my-fraud-id-1",
    type="mule",
    tax_id="012.345.678-90",
    key_id="jon.snow@starkinfra.com",
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    status="canceled",
    tags=["fraud", "mule"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:02:00+00:00"
)
```

### List Pix Fraud Logs

`GET /v2/pix-fraud/log`

Get a paged list of all Pix fraud 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. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `ids` | OPTIONAL | Filter by Pix fraud log ids. |
| `fraudIds` | OPTIONAL | Filter logs by the Pix fraud report ids they belong to. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filter by log types. Options: "created", "failed", "registered", "canceling", "canceled". |

**Request**

```python
import starkinfra

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

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

**Response**

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

Log(
    id="6767676767676767",
    type="registered",
    fraud=PixFraud(
        id="5656565656565656",
        external_id="my-fraud-id-1",
        type="mule",
        tax_id="012.345.678-90",
        key_id="jon.snow@starkinfra.com",
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        status="registered",
        tags=["fraud", "mule"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    errors=[],
    created="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Fraud Log

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

Get a single Pix fraud log by its id.

**Parameters**

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

**Request**

```python
import starkinfra

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

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    type="registered",
    fraud=PixFraud(
        id="5656565656565656",
        external_id="my-fraud-id-1",
        type="mule",
        tax_id="012.345.678-90",
        key_id="jon.snow@starkinfra.com",
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        status="registered",
        tags=["fraud", "mule"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    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-fraud-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/pix-fraud-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/pix-fraud-php.md)
- [Java](https://docs.starkinfra.com/api/v2/pix-fraud-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/pix-fraud-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/pix-fraud-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/pix-fraud-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/pix-fraud-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/pix-fraud-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/pix-fraud-curl.md)