# Pix Request

A Pix Request represents an inbound or outbound Pix payment in the Brazilian instant payment system.

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

### The Pix Request Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix request. |
| `amount` | INTEGER | Amount in cents to be transferred. Example: 100 (R$1.00). |
| `endToEndId` | STRING | Unique end-to-end ID assigned by the Pix system. |
| `fee` | INTEGER | Fee charged in cents for this Pix request. |
| `flow` | STRING | Direction of the Pix request. Options: "in" (received), "out" (sent). |
| `method` | STRING | Method through which this Pix was processed. Options: "manual", "dict", "initiator", "dynamicQrcode", "staticQrcode", "payerQrcode", "subscription", "contactless", "staticContactless". |
| `externalId` | STRING | Unique external ID to prevent duplicates. |
| `initiatorTaxId` | STRING | Tax ID of the payment initiator. |
| `receiverBankCode` | STRING | Bank ISPB code of the receiver. |
| `receiverBranchCode` | STRING | Branch code of the receiver's bank account. |
| `receiverAccountNumber` | STRING | Account number of the receiver. |
| `receiverAccountType` | STRING | Account type of the receiver. Options: "checking", "savings", "salary", "payment". |
| `receiverName` | STRING | Full name of the receiver. |
| `receiverTaxId` | STRING | CPF or CNPJ of the receiver. |
| `senderBankCode` | STRING | Bank ISPB code of the sender. |
| `senderBranchCode` | STRING | Branch code of the sender's bank account. |
| `senderAccountNumber` | STRING | Account number of the sender. |
| `senderAccountType` | STRING | Account type of the sender. Options: "checking", "savings", "salary", "payment". |
| `senderName` | STRING | Full name of the sender. |
| `senderTaxId` | STRING | CPF or CNPJ of the sender. |
| `status` | STRING | Current status. Options: "created", "processing", "success", "failed". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix request. |
| `description` | STRING | Description of the Pix request. |
| `reconciliationId` | STRING | Reconciliation ID for the Pix request. |
| `cashAmount` | INTEGER | Amount in cents to be withdrawal when paying. Example: 1000 (R$10.00). |
| `cashierType` | STRING | Cashier's type for Pix Cash-out and Pix Change. Options: "merchant", "participant", "other". |
| `cashierBankCode` | STRING | Cashier's bank ISPB code for Pix Cash-out and Pix Change. |
| `priority` | STRING | Pix request processing priority. Options: "high", "low". |
| `reason` | STRING | Reason why this Pix request was created. Options: "customerRequest", "subscriptionFlaw", "fraud". |
| `disputeId` | STRING | Id of the Pix Dispute this Pix request refunds. Filled only when reason is "fraud"; empty string otherwise. |
| `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 Requests

`POST /v2/pix-request`

Send Pix payments to any Pix-enabled bank account in Brazil.

To create a manual Pix Request you need the receiver's account information. If you only have a Pix Key, use Get a Pix Key to retrieve the required information before creating the Pix Request.

Every time a participant sends you a Pix, an inbound Pix Request is created and a synchronous POST authorization request is sent to your registered pixRequestUrl, which you must answer with approval or denial within 1 second (HTTP 200) or it is denied by default. Approve with status "approved"; deny with status "denied" and a reason such as "invalidAccountNumber".

You can create up to 100 Pix requests in a single request.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | Amount in cents to be transferred. Example: 100 (R$1.00). |
| `externalId` | REQUIRED | Unique string to prevent duplicates. Repeated externalIds will cause failures. By default, this parameter also blocks any Pix Request that repeats amount and receiver information on the same date. |
| `endToEndId` | REQUIRED | Unique end-to-end ID generated for the Pix request. |
| `senderAccountNumber` | REQUIRED | Account number of the sender. |
| `senderBranchCode` | REQUIRED | Branch code of the sender's bank account. |
| `senderAccountType` | REQUIRED | Account type of the sender. Options: "checking", "savings", "salary", "payment". |
| `senderName` | REQUIRED | Full name of the sender. |
| `senderTaxId` | REQUIRED | CPF or CNPJ of the sender. |
| `receiverAccountNumber` | REQUIRED | Account number of the receiver. |
| `receiverAccountType` | REQUIRED | Account type of the receiver. Options: "checking", "savings", "salary", "payment". |
| `receiverBankCode` | REQUIRED | Bank ISPB code of the receiver. |
| `receiverTaxId` | REQUIRED | CPF or CNPJ of the receiver. |
| `receiverBranchCode` | OPTIONAL | Branch code of the receiver's bank account. |
| `receiverName` | OPTIONAL | Full name of the receiver. |
| `description` | OPTIONAL | Description of the Pix request. |
| `initiatorTaxId` | OPTIONAL | Tax ID of the payment initiator. |
| `reconciliationId` | OPTIONAL | Reconciliation ID for internal reference. |
| `method` | OPTIONAL | Method through which this Pix should be processed. Options: "manual", "dict", "initiator", "dynamicQrcode", "staticQrcode", "payerQrcode", "subscription", "contactless", "staticContactless". |
| `cashAmount` | OPTIONAL | Amount in cents to be withdrawal when paying. Example: 1000 (R$10.00). |
| `cashierType` | OPTIONAL | Cashier's type for Pix Cash-out and Pix Change. Options: "merchant", "participant", "other". |
| `cashierBankCode` | OPTIONAL | Cashier's bank ISPB code for Pix Cash-out and Pix Change. |
| `priority` | OPTIONAL | Pix request processing priority, which selects the message channel used to send it: "high" uses the primary channel and "low" the secondary one. Default is "high". Options: "high", "low". |
| `reason` | OPTIONAL | Reason why this Pix request was created. Default is "customerRequest". Options: "customerRequest", "subscriptionFlaw", "fraud". "fraud" requires disputeId. |
| `disputeId` | CONDITIONALLY REQUIRED | Id of the Pix Dispute being refunded. Required when reason is "fraud" and not allowed with any other reason. The dispute must be one you received and must be awaiting the refund, otherwise the request is refused with invalidDisputeId. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |

**Request**

```python
import starkinfra

requests = starkinfra.pixrequest.create([
    starkinfra.PixRequest(
        amount=1000,
        external_id="my-external-id-1",
        end_to_end_id="E20018183202201011000r01",
        sender_account_number="00000-0",
        sender_branch_code="0001",
        sender_account_type="checking",
        sender_name="Arya Stark",
        sender_tax_id="012.345.678-90",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_bank_code="20018183",
        receiver_tax_id="98.765.432/0001-10",
        receiver_branch_code="0001",
        receiver_name="Jon Snow",
        tags=["transfer", "pix"]
    )
])

for request in requests:
    print(request)
```

**Response**

```python
[
    PixRequest(
        id="5656565656565656",
        amount=1000,
        end_to_end_id="E20018183202201011000r01",
        fee=0,
        flow="out",
        method="manual",
        external_id="my-external-id-1",
        initiator_tax_id="",
        receiver_bank_code="20018183",
        receiver_branch_code="0001",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_name="Jon Snow",
        receiver_tax_id="98.765.432/0001-10",
        sender_bank_code="34052649",
        sender_branch_code="0001",
        sender_account_number="00000-0",
        sender_account_type="checking",
        sender_name="Arya Stark",
        sender_tax_id="012.345.678-90",
        status="created",
        tags=["transfer", "pix"],
        description="",
        reconciliation_id="",
        cash_amount=0,
        cashier_type="",
        cashier_bank_code="",
        priority="high",
        reason="customerRequest",
        created="2022-01-01T00:00:00+00:00",
        updated="2022-01-01T00:00:00+00:00"
    )
]
```

### List Pix Requests

`GET /v2/pix-request`

List and filter all Pix requests. Results are paged.

Every time a participant sends you a Pix, an inbound Pix Request is created and a synchronous POST authorization request is sent to your registered pixRequestUrl, which you must answer with approval or denial within 1 second (HTTP 200) or it is denied by default. Approve with status "approved"; deny with status "denied" and a reason such as "invalidAccountNumber".

**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. |
| `endToEndIds` | OPTIONAL | Filter by end-to-end IDs. |
| `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

requests = starkinfra.pixrequest.query(
    limit=10,
    after="2022-01-01",
    before="2022-12-31",
    status=["success"],
    tags=["pix"]
)

for request in requests:
    print(request)
```

**Response**

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

PixRequest(
    id="5656565656565656",
    amount=1000,
    end_to_end_id="E20018183202201011000r01",
    fee=0,
    flow="out",
    method="manual",
    status="success",
    tags=["pix"],
    priority="high",
    reason="customerRequest",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### Get a Pix Request

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

Get a single Pix request by its id.

**Parameters**

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

**Request**

```python
import starkinfra

request = starkinfra.pixrequest.get("5656565656565656")

print(request)
```

**Response**

```python
PixRequest(
    id="5656565656565656",
    amount=1000,
    end_to_end_id="E20018183202201011000r01",
    fee=0,
    flow="out",
    method="manual",
    external_id="my-external-id-1",
    initiator_tax_id="",
    receiver_bank_code="20018183",
    receiver_branch_code="0001",
    receiver_account_number="10000-0",
    receiver_account_type="checking",
    receiver_name="Jon Snow",
    receiver_tax_id="98.765.432/0001-10",
    sender_bank_code="34052649",
    sender_branch_code="0001",
    sender_account_number="00000-0",
    sender_account_type="checking",
    sender_name="Arya Stark",
    sender_tax_id="012.345.678-90",
    status="success",
    tags=["pix"],
    description="",
    reconciliation_id="",
    cash_amount=0,
    cashier_type="",
    cashier_bank_code="",
    priority="high",
    reason="customerRequest",
    created="2022-01-01T00:00:00+00:00",
    updated="2022-01-01T00:00:00+00:00"
)
```

### List Pix Request Logs

`GET /v2/pix-request/log`

Get a paged list of all Pix request 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. |
| `requestIds` | OPTIONAL | Array of Pix request ids linked to the logs. |
| `types` | OPTIONAL | Filter logs by log types. |

**Request**

```python
import starkinfra

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

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

**Response**

```python
Log(
    id="6767676767676767",
    type="success",
    errors=[],
    request=PixRequest(
        id="5656565656565656",
        amount=1000,
        end_to_end_id="E20018183202201011000r01",
        fee=0,
        flow="out",
        method="manual",
        external_id="my-external-id-1",
        initiator_tax_id="",
        receiver_bank_code="20018183",
        receiver_branch_code="0001",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_name="Jon Snow",
        receiver_tax_id="98.765.432/0001-10",
        sender_bank_code="34052649",
        sender_branch_code="0001",
        sender_account_number="00000-0",
        sender_account_type="checking",
        sender_name="Arya Stark",
        sender_tax_id="012.345.678-90",
        status="success",
        tags=["pix"],
        description="",
        reconciliation_id="",
        cash_amount=0,
        cashier_type="",
        cashier_bank_code="",
        priority="high",
        reason="customerRequest",
        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 Request Log

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

Get a single Pix request 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.pixrequest.log.get("6767676767676767")

print(log)
```

**Response**

```python
Log(
    id="6767676767676767",
    type="success",
    errors=[],
    request=PixRequest(
        id="5656565656565656",
        amount=1000,
        end_to_end_id="E20018183202201011000r01",
        fee=0,
        flow="out",
        method="manual",
        external_id="my-external-id-1",
        initiator_tax_id="",
        receiver_bank_code="20018183",
        receiver_branch_code="0001",
        receiver_account_number="10000-0",
        receiver_account_type="checking",
        receiver_name="Jon Snow",
        receiver_tax_id="98.765.432/0001-10",
        sender_bank_code="34052649",
        sender_branch_code="0001",
        sender_account_number="00000-0",
        sender_account_type="checking",
        sender_name="Arya Stark",
        sender_tax_id="012.345.678-90",
        status="success",
        tags=["pix"],
        description="",
        reconciliation_id="",
        cash_amount=0,
        cashier_type="",
        cashier_bank_code="",
        priority="high",
        reason="customerRequest",
        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-request-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/pix-request-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/pix-request-php.md)
- [Java](https://docs.starkinfra.com/api/v2/pix-request-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/pix-request-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/pix-request-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/pix-request-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/pix-request-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/pix-request-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/pix-request-curl.md)