# Pix Chargeback

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

**Attributes**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | Amount in cents to be charged back. |
| `reason` | REQUIRED | Reason for the chargeback. Options: "flaw", "fraud", "subscriptionFlaw" - the only reasons you can submit on creation. "reversalChargeback" is assigned automatically by the API to chargebacks created from a closed Pix Infraction, and cannot be set directly. |
| `referenceId` | REQUIRED | End-to-end ID of the original Pix transaction. |
| `description` | CONDITIONALLY REQUIRED | Description of the chargeback request. Required when reason is "flaw". |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `bacenId` | OPTIONAL | Filter by the Central Bank ID of the Pix chargeback. |
| `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 of the original Pix transactions to filter by. Max = 30. |
| `status` | OPTIONAL | Filter by status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

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

**Parameters**

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

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

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix chargeback entity. |
| `result` | REQUIRED | Result of the chargeback analysis. Options: "rejected", "accepted", "partiallyAccepted". |
| `analysis` | OPTIONAL | Analysis text explaining the result. Required when rejectionReason is "invalidRequest". |
| `rejectionReason` | OPTIONAL | Reason for rejection. Required when result is "rejected". Options: "other", "noBalance", "accountClosed", "invalidRequest". |
| `reversalReferenceId` | OPTIONAL | Return ID of the reversal used to partially or fully agree to the chargeback. |

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

**Parameters**

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

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

**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. |
| `chargebackIds` | OPTIONAL | Filter by Pix chargeback ids. Max = 30. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filter logs by log types. |

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

**Parameters**

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

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

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