# Pix Reversal

A Pix Reversal allows you to reverse a previously made Pix transfer, sending the funds back to the original sender.

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

### The Pix Reversal Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix reversal. |
| `amount` | INTEGER | Amount in cents to be reversed. |
| `externalId` | STRING | Unique external ID to prevent duplicates. |
| `endToEndId` | STRING | End-to-end ID of the original Pix request to be reversed. |
| `returnId` | STRING | Central Bank return ID generated for the Pix reversal. |
| `reason` | STRING | Reason for the reversal. Options: "fraud", "bankError", "cashierError", "customerRequest". |
| `status` | STRING | Current status. Options: "created", "processing", "success", "failed". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix reversal. |
| `fee` | INTEGER | Fee charged in cents for this reversal. |
| `flow` | STRING | Direction of the reversal. Options: "in" (received), "out" (sent). |
| `description` | STRING | Description of the reversal. |
| `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 Reversals

`POST /v2/pix-reversal`

Reverse a Pix payment by providing the original end-to-end ID.

Pix Reversals can only be created for inbound Pix Requests with status success. Reference the original Pix Request by passing its endToEndId.

When a participant reverses a Pix you successfully sent, an authorization request is sent to your pixReversalUrl (which must differ from your pixRequestUrl); answer within 1 second (HTTP 200) or it is denied by default; if no pixReversalUrl is registered, inbound Pix Reversals are accepted by default.

You can create up to 100 reversals in a single request.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | Amount in cents to be reversed. |
| `endToEndId` | REQUIRED | End-to-end ID of the original Pix request to be reversed. |
| `externalId` | REQUIRED | Unique string to prevent duplicates. By default, this parameter also blocks any Pix Reversal that repeats amount and receiver information on the same date. |
| `reason` | REQUIRED | Reason for the reversal. Options: "fraud", "bankError", "cashierError", "customerRequest". |
| `description` | OPTIONAL | Description of the reversal. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |

**Request**

```python
import starkinfra

reversals = starkinfra.pixreversal.create([
    starkinfra.PixReversal(
        amount=1000,
        external_id="my-reversal-id-1",
        end_to_end_id="E20018183202201060100rq1feOMJqtZ",
        reason="fraud",
        description="reversing a fraudulent transfer",
        tags=["reversal", "pix"]
    )
])

for reversal in reversals:
    print(reversal)
```

**Response**

```python
[
    PixReversal(
        id="5656565656565656",
        amount=1000,
        external_id="my-reversal-id-1",
        end_to_end_id="E20018183202201060100rq1feOMJqtZ",
        return_id="D20018183202202030109X3OoBHG74wo",
        reason="fraud",
        status="created",
        flow="out",
        fee=0,
        description="reversing a fraudulent transfer",
        tags=["reversal", "pix"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Reversals

`GET /v2/pix-reversal`

List and filter all Pix reversals. 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. |
| `externalIds` | OPTIONAL | Filter by external IDs. |
| `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. |

**Request**

```python
import starkinfra

reversals = starkinfra.pixreversal.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["success"],
    external_ids=["my-reversal-id-1"],
    tags=["pix"]
)

for reversal in reversals:
    print(reversal)
```

**Response**

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

PixReversal(
    id="5656565656565656",
    amount=1000,
    external_id="my-reversal-id-1",
    end_to_end_id="E20018183202201060100rq1feOMJqtZ",
    return_id="D20018183202202030109X3OoBHG74wo",
    reason="fraud",
    status="success",
    flow="out",
    fee=0,
    description="reversing a fraudulent transfer",
    tags=["pix"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Get a Pix Reversal

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

Get a single Pix reversal by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix reversal entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

reversal = starkinfra.pixreversal.get("5656565656565656")

print(reversal)
```

**Response**

```python
PixReversal(
    id="5656565656565656",
    amount=1000,
    external_id="my-reversal-id-1",
    end_to_end_id="E20018183202201060100rq1feOMJqtZ",
    return_id="D20018183202202030109X3OoBHG74wo",
    reason="fraud",
    status="success",
    flow="out",
    fee=0,
    description="reversing a fraudulent transfer",
    tags=["pix"],
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### List Pix Reversal Logs

`GET /v2/pix-reversal/log`

Get a paged list of all Pix reversal 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. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `reversalIds` | OPTIONAL | Array of Pix reversal ids linked to the logs. |
| `types` | OPTIONAL | Filter logs by log types. |

**Request**

```python
import starkinfra

logs = starkinfra.pixreversal.log.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    types=["success"],
    reversal_ids=["5656565656565656"]
)

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

**Response**

```python
Log(
    id="6767676767676767",
    type="success",
    reversal=PixReversal(
        id="5656565656565656",
        amount=1000,
        external_id="my-reversal-id-1",
        end_to_end_id="E20018183202201060100rq1feOMJqtZ",
        return_id="D20018183202202030109X3OoBHG74wo",
        reason="fraud",
        status="success",
        flow="out",
        fee=0,
        description="reversing a fraudulent transfer",
        tags=["pix"],
        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 Reversal Log

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

Get a single Pix reversal log by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the log entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkinfra

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

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    type="success",
    reversal=PixReversal(
        id="5656565656565656",
        amount=1000,
        external_id="my-reversal-id-1",
        end_to_end_id="E20018183202201060100rq1feOMJqtZ",
        return_id="D20018183202202030109X3OoBHG74wo",
        reason="fraud",
        status="success",
        flow="out",
        fee=0,
        description="reversing a fraudulent transfer",
        tags=["pix"],
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00: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-reversal-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/pix-reversal-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/pix-reversal-php.md)
- [Java](https://docs.starkinfra.com/api/v2/pix-reversal-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/pix-reversal-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/pix-reversal-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/pix-reversal-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/pix-reversal-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/pix-reversal-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/pix-reversal-curl.md)