# MED

MED is Bacen's Special Return Mechanism (Mecanismo Especial de Devolução), the framework Pix participants use to dispute, return and report problematic transactions.

Through MED, participants open and answer infractions against suspicious Pix transactions, request and respond to chargebacks to refund disputed payments, and report or consult fraud markers registered against payers in Bacen's systems.

This guide walks you through every MED resource: opening and answering infractions, requesting chargebacks, reporting and consulting fraud markers, and handling disputes via MED 2.0.

**RESOURCE SUMMARY**

Pix InfractionRespond to infraction reports against Pix transactions.Pix ChargebackRequest and respond to refunds for Pix transactions through MED.Pix FraudReport and consult fraud markers against payers.Pix DisputeRequest, cancel and consult Pix disputes for transactions through MED 2.0.

## Pix Infraction Overview

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

**Parameters**

| 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: "fraud", "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". |

### Sending a Pix Infraction

Create a Pix Infraction to report a Pix transaction suspected of fraud. The Central Bank keeps track of the number of closed infractions for each Pix Key so participants can monitor possible fraudulent accounts.

### Receiving a Pix Infraction

When another participant reports an infraction against one of your transactions, an inbound Pix Infraction is created for you to analyze and answer within 7 days of delivery.

### The Pix Infraction Status

After creation, you can use asynchronous Webhooks to monitor status changes of a Pix Infraction. A closed status indicates whether the other party accepted or rejected the infraction.

Pix Infractions you report (outbound) follow this life cycle:

To monitor received Pix Infractions, listen for webhooks and filter by the flow attribute; you must analyze and answer an inbound infraction within 7 days of delivery. Inbound Pix Infractions follow this life cycle:

| Status | Description |
| --- | --- |
| Created | The Pix Infraction was successfully created at Stark Infra. |
| Failed | The Pix Infraction could not be processed. |
| Delivered | The Pix Infraction was delivered to the other party. |
| Closed | The Pix Infraction was answered and the other party accepted or rejected it. |
| Canceled | The Pix Infraction was canceled. |

### The Pix Infraction Logs

Every time we change a Pix Infraction, we create a Log. Logs are useful for understanding the life cycle of each Pix Infraction, and we fire a Webhook whenever a new Log is created. The possible Pix Infraction Logs:

For inbound Pix Infractions:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Pix Infraction was successfully created at Stark Infra. |
| Failed | Failed | The Pix Infraction could not be processed. |
| Delivered | Delivered | The Pix Infraction was delivered to the other party. |
| Closed | Closed | The Pix Infraction was answered and the other party accepted or rejected it. |
| Canceled | Canceled | The Pix Infraction was canceled. |

### List Pix Infractions

`GET /v2/pix-infraction`

List and filter all Pix infractions. Results are paged.

**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.

**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.

**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.

**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.

**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.

**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"
)
```

## Pix Chargeback Overview

A Pix Chargeback allows you to request the return of funds from a Pix transaction made in error or due to fraud, and to respond to chargebacks opened against your transactions, through MED.

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

### The Pix Chargeback Object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix chargeback. |
| `amount` | INTEGER | Amount in cents to be charged back. |
| `referenceId` | STRING | End-to-end ID of the original Pix transaction. |
| `reason` | STRING | Reason for the chargeback. Options: "fraud", "flaw", "reversalChargeback". |
| `result` | STRING | Result of the chargeback. Options: "rejected", "accepted", "partiallyAccepted". |
| `analysis` | STRING | Analysis text from the responding party. |
| `description` | STRING | Description of the chargeback request. |
| `senderBankCode` | STRING | Bank ISPB code of the sender in the original transaction. |
| `receiverBankCode` | STRING | Bank ISPB code of the receiver in the original transaction. |
| `rejectionReason` | STRING | Reason for rejection if the chargeback was not agreed. Options: "other", "noBalance", "accountClosed", "invalidRequest". |
| `bacenId` | STRING | Central Bank ID for this Pix chargeback. |
| `disputeId` | STRING | Unique id of the Pix dispute associated with the chargeback. |
| `isMonitoringRequired` | BOOLEAN | Indicates whether monitoring is required for this chargeback. |
| `reversalBankCode` | STRING | Bank ISPB code of the account that received the reversal. |
| `reversalBranchCode` | STRING | Branch code of the account that received the reversal. |
| `reversalAccountNumber` | STRING | Number of the account that received the reversal. |
| `reversalAccountType` | STRING | Type of the account that received the reversal. Options: "checking", "savings", "salary", "payment", "other". |
| `reversalTaxId` | STRING | Tax ID (CPF/CNPJ) of the account that received the reversal. |
| `status` | STRING | Current status. Options: "created", "failed", "delivered", "closed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix chargeback. |
| `flow` | STRING | Direction of the chargeback. Options: "out" (you requested), "in" (requested against you). |
| `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". |

### Receiving a Pix Chargeback

When another participant requests a chargeback against one of your transactions, an inbound Pix Chargeback is created, which you must analyze and answer within 24 hours.

### The Pix Chargeback Status

After creation, you can use asynchronous Webhooks to monitor status changes of a Pix Chargeback.

Pix Chargebacks you open (outbound) follow this life cycle:

Pix Chargebacks you receive (inbound) follow this life cycle:

| Status | Description |
| --- | --- |
| Created | The Pix Chargeback was successfully created at Stark Infra. |
| Failed | The Pix Chargeback could not be processed. |
| Delivered | The Pix Chargeback was delivered to the other participant for analysis. |
| Closed | The Pix Chargeback was answered and resolved by the other participant. |
| Canceled | The Pix Chargeback was canceled before being closed. |

### The Pix Chargeback Logs

Every time we change a Pix Chargeback, we create a Log. Logs are useful for understanding the life cycle of each Pix Chargeback, and we fire a Webhook whenever a new Log is created. The possible Pix Chargeback Logs:

For inbound Pix Chargebacks:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Pix Chargeback was successfully created at Stark Infra. |
| Failed | Failed | The Pix Chargeback could not be processed. |
| Delivered | Delivered | The Pix Chargeback was delivered to the other participant for analysis. |
| Closed | Closed | The Pix Chargeback was answered and resolved by the other participant. |
| Canceled | Canceled | The Pix Chargeback was canceled before being closed. |

### Create Pix Chargebacks

`POST /v2/pix-chargeback`

Request a chargeback for a Pix transaction.

A Pix Chargeback requests the reversal of a Pix transaction and should only be created after a corresponding Pix Infraction is completed (or a system malfunction). The other participant must answer within 24 hours. The only supported reason is flaw — reversing an erroneous transaction caused by a system malfunction.

**Request**

```python
import starkinfra

chargebacks = starkinfra.pixchargeback.create([
    starkinfra.PixChargeback(
        amount=1000,
        reason="flaw",
        reference_id="E20018183202201201450u34sDjD7334",
        description="Chargeback request due to confirmed fraud",
        tags=["chargeback", "fraud"]
    )
])

for chargeback in chargebacks:
    print(chargeback)
```

**Response**

```python
[
    PixChargeback(
        id="5656565656565656",
        amount=1000,
        reference_id="E20018183202201201450u34sDjD7334",
        reason="flaw",
        result=None,
        analysis=None,
        description="Chargeback request due to confirmed fraud",
        sender_bank_code="20018183",
        receiver_bank_code="34052649",
        rejection_reason=None,
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        dispute_id="d20018183202201201450u34sDjD7334",
        is_monitoring_required=False,
        reversal_bank_code=None,
        reversal_branch_code=None,
        reversal_account_number=None,
        reversal_account_type=None,
        reversal_tax_id=None,
        status="created",
        tags=["chargeback", "fraud"],
        flow="out",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Chargebacks

`GET /v2/pix-chargeback`

List and filter all Pix chargebacks. Results are paged.

**Request**

```python
import starkinfra

chargebacks = starkinfra.pixchargeback.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["delivered"],
    ids=["5656565656565656"],
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    reference_ids=["E20018183202201201450u34sDjD7334"],
    flow="out",
    tags=["fraud"]
)

for chargeback in chargebacks:
    print(chargeback)
```

**Response**

```python
PixChargeback(
    id="5656565656565656",
    amount=1000,
    reference_id="E20018183202201201450u34sDjD7334",
    reason="fraud",
    result=None,
    analysis=None,
    description="Chargeback request due to confirmed fraud",
    sender_bank_code="20018183",
    receiver_bank_code="34052649",
    rejection_reason=None,
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="d20018183202201201450u34sDjD7334",
    is_monitoring_required=False,
    reversal_bank_code=None,
    reversal_branch_code=None,
    reversal_account_number=None,
    reversal_account_type=None,
    reversal_tax_id=None,
    status="delivered",
    tags=["fraud"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Get a Pix Chargeback

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

Get a single Pix chargeback by its id.

**Request**

```python
import starkinfra

chargeback = starkinfra.pixchargeback.get("5656565656565656")

print(chargeback)
```

**Response**

```python
PixChargeback(
    id="5656565656565656",
    amount=1000,
    reference_id="E20018183202201201450u34sDjD7334",
    reason="fraud",
    result=None,
    analysis=None,
    description="Chargeback request due to confirmed fraud",
    sender_bank_code="20018183",
    receiver_bank_code="34052649",
    rejection_reason=None,
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="d20018183202201201450u34sDjD7334",
    is_monitoring_required=False,
    reversal_bank_code=None,
    reversal_branch_code=None,
    reversal_account_number=None,
    reversal_account_type=None,
    reversal_tax_id=None,
    status="delivered",
    tags=["fraud"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Update a Pix Chargeback

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

Respond to an incoming Pix chargeback request.

**Request**

```python
import starkinfra

chargeback = starkinfra.pixchargeback.update(
    "5656565656565656",
    result="agreed",
    analysis="Fraud confirmed, agreeing to chargeback.",
    reversal_reference_id="D20018183202201201450u34sDjD7334"
)

print(chargeback)
```

**Response**

```python
PixChargeback(
    id="5656565656565656",
    amount=1000,
    reference_id="E20018183202201201450u34sDjD7334",
    reason="fraud",
    result="agreed",
    analysis="Fraud confirmed, agreeing to chargeback.",
    description="Chargeback request due to confirmed fraud",
    sender_bank_code="20018183",
    receiver_bank_code="34052649",
    rejection_reason=None,
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="d20018183202201201450u34sDjD7334",
    is_monitoring_required=False,
    reversal_bank_code="20018183",
    reversal_branch_code="0001",
    reversal_account_number="5341615776841728",
    reversal_account_type="checking",
    reversal_tax_id="012.345.678-90",
    status="closed",
    tags=["chargeback", "fraud"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-06-01T00:00:00+00:00"
)
```

### Cancel a Pix Chargeback

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

Cancel a Pix chargeback you requested.

**Request**

```python
import starkinfra

chargeback = starkinfra.pixchargeback.cancel("5656565656565656")

print(chargeback)
```

**Response**

```python
PixChargeback(
    id="5656565656565656",
    amount=1000,
    reference_id="E20018183202201201450u34sDjD7334",
    reason="fraud",
    result=None,
    analysis=None,
    description="Chargeback request due to confirmed fraud",
    sender_bank_code="20018183",
    receiver_bank_code="34052649",
    rejection_reason=None,
    bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
    dispute_id="d20018183202201201450u34sDjD7334",
    is_monitoring_required=False,
    reversal_bank_code=None,
    reversal_branch_code=None,
    reversal_account_number=None,
    reversal_account_type=None,
    reversal_tax_id=None,
    status="canceled",
    tags=["chargeback", "fraud"],
    flow="out",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-06-01T00:00:00+00:00"
)
```

### List Pix Chargeback Logs

`GET /v2/pix-chargeback/log`

Get a paged list of all Pix chargeback logs.

**Request**

```python
import starkinfra

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

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

**Response**

```python
Log(
    id="6767676767676767",
    chargeback=PixChargeback(
        id="5656565656565656",
        amount=1000,
        reference_id="E20018183202201201450u34sDjD7334",
        reason="flaw",
        result=None,
        analysis=None,
        description="Chargeback request due to confirmed fraud",
        sender_bank_code="20018183",
        receiver_bank_code="34052649",
        rejection_reason=None,
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        dispute_id="d20018183202201201450u34sDjD7334",
        is_monitoring_required=False,
        reversal_bank_code=None,
        reversal_branch_code=None,
        reversal_account_number=None,
        reversal_account_type=None,
        reversal_tax_id=None,
        status="delivered",
        tags=["fraud"],
        flow="out",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    type="delivered",
    errors=[],
    created="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Chargeback Log

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

Get a single Pix chargeback log by its id.

**Request**

```python
import starkinfra

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

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    chargeback=PixChargeback(
        id="5656565656565656",
        amount=1000,
        reference_id="E20018183202201201450u34sDjD7334",
        reason="flaw",
        result=None,
        analysis=None,
        description="Chargeback request due to confirmed fraud",
        sender_bank_code="20018183",
        receiver_bank_code="34052649",
        rejection_reason=None,
        bacen_id="ccf9bd9c-e99d-999e-bab9-b999ca999f99",
        dispute_id="d20018183202201201450u34sDjD7334",
        is_monitoring_required=False,
        reversal_bank_code=None,
        reversal_branch_code=None,
        reversal_account_number=None,
        reversal_account_type=None,
        reversal_tax_id=None,
        status="delivered",
        tags=["fraud"],
        flow="out",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    type="delivered",
    errors=[],
    created="2022-01-01T00:01:00+00:00"
)
```

## Pix Fraud Overview

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

**Parameters**

| 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.

**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.

**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.

**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.

**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.

### Get a Pix Fraud Log

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

Get a single Pix fraud log by its id.

## Pix Dispute Overview

A Pix Dispute allows you to request, cancel and consult disputes related to Pix transactions through MED 2.0.

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

### The Pix Dispute Object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix dispute. |
| `referenceId` | STRING | End-to-end ID of the original Pix transaction. |
| `bacenId` | STRING | Central Bank's unique ID for the Pix dispute. |
| `method` | STRING | Method of the dispute. Options: "scam", "unauthorized", "coercion", "invasion", "other", "unknown". |
| `description` | STRING | Description of the Pix dispute. |
| `operatorEmail` | STRING | Contact email of the operator responsible for the Pix dispute. |
| `operatorPhone` | STRING | Contact phone number of the operator responsible for the Pix dispute. |
| `status` | STRING | Current status. Options: "created", "failed", "delivered", "analysed", "processing", "closed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix dispute. |
| `flow` | STRING | Direction of the dispute. Options: "out" (you initiated), "in" (raised against you). |
| `minTransactionAmount` | INTEGER | Minimum amount in cents of the transactions to be tracked in the dispute. |
| `maxTransactionCount` | INTEGER | Maximum number of transactions to be tracked in the dispute. |
| `maxHopCount` | INTEGER | Maximum number of hops to be tracked in the dispute. |
| `maxHopInterval` | INTEGER | Maximum interval in seconds between hops to be tracked in the dispute. |
| `transactions` | LIST OF OBJECTS | List of transaction objects tracked in the dispute. |
| `transactions.endToEndId` | STRING | End-to-end ID of the tracked Pix transaction. |
| `transactions.amount` | INTEGER | Transaction amount in cents. |
| `transactions.nominalAmount` | INTEGER | Refundable amount in cents of the transaction. |
| `transactions.senderId` | STRING | Bacen-generated pseudo ID for the sender, used only for transaction-tracking context (not a real account identifier). |
| `transactions.senderType` | STRING | Type of the sender entity. Options: "individual", "business". |
| `transactions.senderTaxIdCreated` | STRING | Returned only for CNPJ tax IDs: the date the sender company was opened. Example: "2020-04-23T23:00:00.000000+00:00". |
| `transactions.senderAccountCreated` | STRING | Datetime when the sender's account was opened. Example: "2020-04-23T23:00:00.000000+00:00". |
| `transactions.senderBankCode` | STRING | Bank code of the sender's institution. |
| `transactions.receiverId` | STRING | Bacen-generated pseudo ID for the receiver, used only for transaction-tracking context (not a real account identifier). |
| `transactions.receiverType` | STRING | Type of the receiver entity. Options: "individual", "business". |
| `transactions.receiverTaxIdCreated` | STRING | Returned only for CNPJ tax IDs: the date the receiver company was opened. Example: "2020-04-23T23:00:00.000000+00:00". |
| `transactions.receiverAccountCreated` | STRING | Datetime when the receiver's account was opened. Example: "2020-04-23T23:00:00.000000+00:00". |
| `transactions.receiverBankCode` | STRING | Bank code of the receiver's institution. |
| `transactions.settled` | STRING | Datetime when the transaction was settled. Example: "2020-04-23T23:00:00.000000+00:00". |
| `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 Disputes

`POST /v2/pix-dispute`

Initiate a Pix dispute for a transaction.

**Request**

```python
import starkinfra

disputes = starkinfra.pixdispute.create([
    starkinfra.PixDispute(
        reference_id="E20018183202201201450u34sDjD7334",
        method="scam",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        description="Transaction reported by the account holder as fraudulent.",
        min_transaction_amount=100,
        max_transaction_count=10,
        max_hop_count=5,
        max_hop_interval=3600,
        tags=["dispute", "scam"]
    )
])

for dispute in disputes:
    print(dispute)
```

**Response**

```python
[
    PixDispute(
        id="5656565656565656",
        reference_id="E20018183202201201450u34sDjD7334",
        bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
        method="scam",
        description="Transaction reported by the account holder as fraudulent.",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        status="created",
        tags=["dispute", "scam"],
        flow="out",
        min_transaction_amount=100,
        max_transaction_count=10,
        max_hop_count=5,
        max_hop_interval=3600,
        transactions=[],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Disputes

`GET /v2/pix-dispute`

List and filter all Pix disputes. Results are paged.

**Request**

```python
import starkinfra

disputes = starkinfra.pixdispute.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status="delivered",
    flow="out",
    bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
    reference_ids=["E20018183202201201450u34sDjD7334"],
    ids=["5656565656565656", "4545454545454545"],
    tags=["scam"]
)

for dispute in disputes:
    print(dispute)
```

**Response**

```python
PixDispute(
    id="5656565656565656",
    reference_id="E20018183202201201450u34sDjD7334",
    bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
    method="scam",
    description="Transaction reported by the account holder as fraudulent.",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    status="delivered",
    tags=["scam"],
    flow="out",
    min_transaction_amount=100,
    max_transaction_count=10,
    max_hop_count=5,
    max_hop_interval=3600,
    transactions=[],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Get a Pix Dispute

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

Get a single Pix dispute by its id.

**Request**

```python
import starkinfra

dispute = starkinfra.pixdispute.get("5656565656565656")

print(dispute)
```

**Response**

```python
PixDispute(
    id="5656565656565656",
    reference_id="E20018183202201201450u34sDjD7334",
    bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
    method="scam",
    description="Transaction reported by the account holder as fraudulent.",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    status="delivered",
    tags=["dispute", "scam"],
    flow="out",
    min_transaction_amount=100,
    max_transaction_count=10,
    max_hop_count=5,
    max_hop_interval=3600,
    transactions=[],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Cancel a Pix Dispute

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

Cancel a Pix dispute you initiated.

**Request**

```python
import starkinfra

dispute = starkinfra.pixdispute.cancel("5656565656565656")

print(dispute)
```

**Response**

```python
PixDispute(
    id="5656565656565656",
    reference_id="E20018183202201201450u34sDjD7334",
    bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
    method="scam",
    description="Transaction reported by the account holder as fraudulent.",
    operator_email="ned.stark@starkbank.com",
    operator_phone="+5511999999999",
    status="canceled",
    tags=["dispute", "scam"],
    flow="out",
    min_transaction_amount=100,
    max_transaction_count=10,
    max_hop_count=5,
    max_hop_interval=3600,
    transactions=[],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-06-01T00:00:00+00:00"
)
```

### List Pix Dispute Logs

`GET /v2/pix-dispute/log`

Get a paged list of all Pix dispute logs.

**Request**

```python
import starkinfra

logs = starkinfra.pixdispute.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    types=["delivered"],
    dispute_ids=["5656565656565656"],
    ids=["6767676767676767"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    type="delivered",
    dispute=PixDispute(
        id="5656565656565656",
        reference_id="E20018183202201201450u34sDjD7334",
        bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
        method="scam",
        description="Transaction reported by the account holder as fraudulent.",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        status="delivered",
        tags=["dispute", "scam"],
        flow="out",
        min_transaction_amount=100,
        max_transaction_count=10,
        max_hop_count=5,
        max_hop_interval=3600,
        transactions=[],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    ),
    created="2022-01-01T00:01:00+00:00"
)
```

### Get a Pix Dispute Log

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

Get a single Pix dispute log by its id.

**Request**

```python
import starkinfra

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

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    type="delivered",
    dispute=PixDispute(
        id="5656565656565656",
        reference_id="E20018183202201201450u34sDjD7334",
        bacen_id="817fc523-9e9d-40ab-9e53-dacb71454a05",
        method="scam",
        description="Transaction reported by the account holder as fraudulent.",
        operator_email="ned.stark@starkbank.com",
        operator_phone="+5511999999999",
        status="delivered",
        tags=["dispute", "scam"],
        flow="out",
        min_transaction_amount=100,
        max_transaction_count=10,
        max_hop_count=5,
        max_hop_interval=3600,
        transactions=[],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:01:00+00:00"
    ),
    created="2022-01-01T00:01:00+00:00"
)
```

---

## Other Languages

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