# Pix Pull Request

A Pix Pull Request is a single charge issued against an active Pix Pull Subscription (Pix Automático), pulling a payment from the payer's account.

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

### The Pix Pull Request Object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the Pix pull request. |
| `amount` | INTEGER | Amount in cents to be pulled. |
| `description` | STRING | Description of the pull request. |
| `due` | STRING | Due datetime for the pull. |
| `endToEndId` | STRING | End-to-end id of the Pix pull request. |
| `reconciliationId` | STRING | Reconciliation id (txid) of the pull. |
| `subscriptionId` | STRING | Id of the Pix pull subscription this request belongs to. |
| `subscriptionBacenId` | STRING | Central Bank id of the related subscription. |
| `receiverName` | STRING | Name of the receiver (creditor). |
| `receiverTaxId` | STRING | CPF or CNPJ of the receiver. |
| `receiverBankCode` | STRING | Bank ISPB code of the receiver. |
| `receiverAccountNumber` | STRING | Account number of the receiver. |
| `receiverBranchCode` | STRING | Branch code of the receiver's account. |
| `receiverAccountType` | STRING | Type of the receiver's account. |
| `senderTaxId` | STRING | CPF or CNPJ of the payer (debtor). |
| `senderBankCode` | STRING | Bank ISPB code of the payer. |
| `senderFinalName` | STRING | Name of the final payer, when different from the account holder. |
| `senderFinalTaxId` | STRING | CPF or CNPJ of the final payer, when different from the account holder. |
| `attemptType` | STRING | Pull attempt type. Options: "default", "scheduledRetry", "instantRetry". |
| `tags` | LIST OF STRINGS | Tags associated with the Pix pull request. |
| `flow` | STRING | Direction of the pull request. Options: "out" (you are the receiver), "in" (you are the payer). |
| `status` | STRING | Current status. Options: "created", "processing", "scheduled", "denied", "success", "failed", "canceled", "expired". |
| `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 Pull Requests

`POST /v2/pix-pull-request`

Issue charges against active Pix pull subscriptions.

As the receiver bank, create a Pix Pull Request to instruct a debit from the payer's account on a scheduled date. Stark Infra verifies that the subscription is approved, the amount is within the authorized limit, the settlement date matches the subscription's charge cycle, payer/receiver details match the contract, the request is made between 10 and 2 days before settlement, and there is no other scheduled request for the same cycle.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `requests` | REQUIRED | List of Pix pull request objects to be created. Min = 1, Max = 100. The parameters below describe the fields of each object. |
| `subscriptionId` | REQUIRED | Id of the active Pix pull subscription to charge. |
| `amount` | REQUIRED | Amount in cents to be pulled. |
| `due` | REQUIRED | Due datetime for the pull. |
| `attemptType` | REQUIRED | Pull attempt type. Options: "default", "scheduledRetry", "instantRetry". |
| `endToEndId` | REQUIRED | End-to-end id of the Pix pull request. |
| `reconciliationId` | REQUIRED | Reconciliation id (txid) of the pull. |
| `receiverAccountNumber` | REQUIRED | Account number of the receiver. |
| `receiverAccountType` | REQUIRED | Type of the receiver's account. |
| `receiverBankCode` | OPTIONAL | Bank ISPB code of the receiver. |
| `receiverBranchCode` | OPTIONAL | Branch code of the receiver's account. |
| `description` | OPTIONAL | Description of the pull request. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. |

**Request**

```python
import starkinfra

requests = starkinfra.pixpullrequest.create([
    starkinfra.PixPullRequest(
        subscription_id="5656565656565656",
        amount=1000,
        due="2022-02-01T00:00:00+00:00",
        attempt_type="default",
        end_to_end_id="E20018183202201010000000000001",
        reconciliation_id="txid1234567890",
        receiver_account_number="00000-0",
        receiver_account_type="checking",
        tags=["automatic", "pix"]
    )
])

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

**Response**

```python
[
    PixPullRequest(
        id="4646464646464646",
        amount=1000,
        description="",
        due="2022-02-01T00:00:00+00:00",
        end_to_end_id="E20018183202201010000000000001",
        reconciliation_id="txid1234567890",
        subscription_id="5656565656565656",
        subscription_bacen_id="RR20220101200181830000000000001",
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        receiver_bank_code="20018183",
        receiver_account_number="00000-0",
        receiver_branch_code="0001",
        receiver_account_type="checking",
        sender_tax_id="012.345.678-90",
        sender_bank_code="00000000",
        sender_final_name="",
        sender_final_tax_id="",
        attempt_type="default",
        tags=["automatic", "pix"],
        flow="out",
        status="created",
        created="2022-01-15T00:00:00+00:00",
        updated="2022-01-15T00:00:00+00:00"
    )
]
```

### List Pix Pull Requests

`GET /v2/pix-pull-request`

List and filter all Pix pull requests. 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. |
| `ids` | OPTIONAL | List of strings to get specific entities by ids. |
| `subscriptionIds` | OPTIONAL | Filter by the Pix pull subscription ids the requests belong to. |
| `endToEndIds` | OPTIONAL | Filter by the end-to-end ids of the requests. |
| `externalIds` | OPTIONAL | Filter by the external ids of the requests. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `status` | OPTIONAL | Filter by status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |
| `attemptTypes` | OPTIONAL | Filter by attempt type. Options: "default", "scheduledRetry", "instantRetry". |
| `flows` | OPTIONAL | Filter by flow direction. Options: "in", "out". |

**Request**

```python
import starkinfra

requests = starkinfra.pixpullrequest.query(
    limit=10,
    subscription_ids=["5656565656565656"]
)

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

**Response**

```python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="out",
    status="success",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-02-01T00:00:00+00:00"
)
```

### Get a Pix Pull Request

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

Get a single Pix pull request by its id.

**Parameters**

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

**Request**

```python
import starkinfra

request = starkinfra.pixpullrequest.get("4646464646464646")

print(request)
```

**Response**

```python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="out",
    status="success",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-02-01T00:00:00+00:00"
)
```

### Update a Pix Pull Request

`PATCH /v2/pix-pull-request/:id`

Schedule or deny a Pix pull request. Only the payer may update a pull request.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix pull request entity. |
| `status` | REQUIRED | New status. Options: "scheduled", "denied". |
| `reason` | OPTIONAL | Reason for the status change, required when denying. Options: "senderAccountClosed", "senderAccountBlocked", "amountNotAllowed". |

**Request**

```python
import starkinfra

request = starkinfra.pixpullrequest.update(
    "4646464646464646",
    status="denied",
    reason="senderAccountClosed"
)

print(request)
```

**Response**

```python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="in",
    status="denied",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-01-16T00:00:00+00:00"
)
```

### Cancel a Pix Pull Request

`DELETE /v2/pix-pull-request/:id`

Cancel a Pix pull request.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Pix pull request entity. |
| `reason` | REQUIRED | Reason for the cancellation. The available values depend on whether you are the sender or the receiver. Options: "accountClosed", "accountBlocked", "pixRequestFailed", "other", "senderUserRequested", "receiverUserRequested". |

**Request**

```python
import starkinfra

request = starkinfra.pixpullrequest.cancel(
    "4646464646464646",
    reason="senderAccountClosed"
)

print(request)
```

**Response**

```python
PixPullRequest(
    id="4646464646464646",
    amount=1000,
    description="",
    due="2022-02-01T00:00:00+00:00",
    end_to_end_id="E20018183202201010000000000001",
    reconciliation_id="txid1234567890",
    subscription_id="5656565656565656",
    subscription_bacen_id="RR20220101200181830000000000001",
    receiver_name="Iron Bank S.A.",
    receiver_tax_id="20.018.183/0001-80",
    receiver_bank_code="20018183",
    receiver_account_number="00000-0",
    receiver_branch_code="0001",
    receiver_account_type="checking",
    sender_tax_id="012.345.678-90",
    sender_bank_code="00000000",
    sender_final_name="",
    sender_final_tax_id="",
    attempt_type="default",
    tags=["automatic", "pix"],
    flow="out",
    status="canceled",
    created="2022-01-15T00:00:00+00:00",
    updated="2022-01-16T00:00:00+00:00"
)
```

### List Pix Pull Request Logs

`GET /v2/pix-pull-request/log`

Get a paged list of all Pix pull 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. |
| `requestIds` | OPTIONAL | Filter logs by the Pix pull request ids they belong to. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `types` | OPTIONAL | Filter by log types. Options: "created", "sent", "scheduled", "denied", "success", "failed", "canceling", "canceled", "expired". |

**Request**

```python
import starkinfra

logs = starkinfra.pixpullrequest.log.query(
    limit=10,
    types=["success"]
)

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

**Response**

```python
Log(
    id="5757575757575757",
    request=PixPullRequest(
        id="4646464646464646",
        amount=1000,
        description="",
        due="2022-02-01T00:00:00+00:00",
        end_to_end_id="E20018183202201010000000000001",
        reconciliation_id="txid1234567890",
        subscription_id="5656565656565656",
        subscription_bacen_id="RR20220101200181830000000000001",
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        receiver_bank_code="20018183",
        receiver_account_number="00000-0",
        receiver_branch_code="0001",
        receiver_account_type="checking",
        sender_tax_id="012.345.678-90",
        sender_bank_code="00000000",
        sender_final_name="",
        sender_final_tax_id="",
        attempt_type="default",
        tags=["automatic", "pix"],
        flow="out",
        status="success",
        created="2022-01-15T00:00:00+00:00",
        updated="2022-02-01T00:00:00+00:00"
    ),
    type="success",
    errors=[],
    reason="",
    description="The Pix Pull Request was settled.",
    created="2022-02-01T00:00:00+00:00"
)
```

### Get a Pix Pull Request Log

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

Get a single Pix pull request log by its id.

**Parameters**

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

**Request**

```python
import starkinfra

log = starkinfra.pixpullrequest.log.get("5757575757575757")

print(log)
```

**Response**

```python
Log(
    id="5757575757575757",
    request=PixPullRequest(
        id="4646464646464646",
        amount=1000,
        description="",
        due="2022-02-01T00:00:00+00:00",
        end_to_end_id="E20018183202201010000000000001",
        reconciliation_id="txid1234567890",
        subscription_id="5656565656565656",
        subscription_bacen_id="RR20220101200181830000000000001",
        receiver_name="Iron Bank S.A.",
        receiver_tax_id="20.018.183/0001-80",
        receiver_bank_code="20018183",
        receiver_account_number="00000-0",
        receiver_branch_code="0001",
        receiver_account_type="checking",
        sender_tax_id="012.345.678-90",
        sender_bank_code="00000000",
        sender_final_name="",
        sender_final_tax_id="",
        attempt_type="default",
        tags=["automatic", "pix"],
        flow="out",
        status="success",
        created="2022-01-15T00:00:00+00:00",
        updated="2022-02-01T00:00:00+00:00"
    ),
    type="success",
    errors=[],
    reason="",
    description="The Pix Pull Request was settled.",
    created="2022-02-01T00:00: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-pull-request-python.md)
- [Node.js](https://docs.starkinfra.com/api/v2/pix-pull-request-node.md)
- [PHP](https://docs.starkinfra.com/api/v2/pix-pull-request-php.md)
- [Java](https://docs.starkinfra.com/api/v2/pix-pull-request-java.md)
- [Ruby](https://docs.starkinfra.com/api/v2/pix-pull-request-ruby.md)
- [Elixir](https://docs.starkinfra.com/api/v2/pix-pull-request-elixir.md)
- [.NET](https://docs.starkinfra.com/api/v2/pix-pull-request-dotnet.md)
- [Go](https://docs.starkinfra.com/api/v2/pix-pull-request-go.md)
- [Clojure](https://docs.starkinfra.com/api/v2/pix-pull-request-clojure.md)
- [cURL](https://docs.starkinfra.com/api/v2/pix-pull-request-curl.md)