# Pix Dispute

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

**Attributes**

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `referenceId` | REQUIRED | End-to-end ID of the original Pix transaction. |
| `method` | REQUIRED | Method of the dispute. Options: "scam", "unauthorized", "coercion", "invasion", "other", "unknown". |
| `operatorEmail` | REQUIRED | Contact email of the operator responsible for the Pix dispute. |
| `operatorPhone` | REQUIRED | Contact phone number of the operator responsible for the Pix dispute. |
| `description` | OPTIONAL | Description of the Pix dispute. Required when method is "other". |
| `minTransactionAmount` | OPTIONAL | Minimum amount in cents of the transactions to be tracked in the dispute. |
| `maxHopCount` | OPTIONAL | Maximum number of hops to be tracked in the dispute. |
| `maxHopInterval` | OPTIONAL | Maximum interval in seconds between hops to be tracked in the dispute. |
| `maxTransactionCount` | OPTIONAL | Maximum number of transactions to be tracked in the dispute. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `bacenId` | OPTIONAL | Filter for the Central Bank's unique ID of the Pix dispute. |
| `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. |
| `flow` | OPTIONAL | Filter by flow direction. Options: "in", "out". |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `referenceIds` | OPTIONAL | List of end-to-end IDs to get disputes by their original Pix transactions. |
| `status` | OPTIONAL | Filter by status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

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

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

**Parameters**

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

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

**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. |
| `disputeIds` | OPTIONAL | List of strings to get logs by their Pix dispute ids. |
| `ids` | OPTIONAL | Filter by Pix dispute ids. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filter logs by log types. |

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

**Parameters**

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

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

## 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-dispute-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/pix-dispute-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/pix-dispute-php.md)
- [Java](https://docs.starkinfra.com/api/v2/pix-dispute-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/pix-dispute-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/pix-dispute-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/pix-dispute-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/pix-dispute-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/pix-dispute-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/pix-dispute-curl.md)