# Pix QR Code Payment

Here we will teach you how to create and manage brcode payments.

### The Brcode Payment object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the brcode payment. |
| `amount` | INTEGER | Payment amount in cents. |
| `brcode` | STRING | Brcode that describes the payment. |
| `created` | STRING | Creation datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `description` | STRING | Text displayed in the bank statement. |
| `fee` | INTEGER | Fee charged in cents. |
| `name` | STRING | Receiver full name. |
| `rules` | LIST OF OBJECTS | List of rule objects with key and value. |
| `scheduled` | STRING | Scheduled payment datetime. Example: "2020-04-23T23:00:00.000000+00:00". |
| `status` | STRING | Current payment status. Options: "created", "processing", "confirmed", "success", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the brcode payment. |
| `taxId` | STRING | Receiver CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the payment. |
| `type` | STRING | Type of the brcode payment. |
| `updated` | STRING | Last update datetime. Example: "2020-04-23T23:00:00.000000+00:00". |

### Create Brcode Payments

`POST /v2/brcode-payment`

Use this route to pay registered brcodes generated at Stark Bank or at other financial institutions using the available balance in your Stark Bank account.

**NOTE:**Initially, the brcode entity amount will be zero because the brcode is processed asynchronously.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `brcode` | REQUIRED | Brcode that describes the payment. |
| `description` | REQUIRED | Text to be displayed in your statement. Min length = 10. |
| `taxId` | REQUIRED | Receiver CPF (11 digits formatted or unformatted) or CNPJ (14 digits formatted or unformatted). Example: 012.345.678-90. |
| `amount` | CONDITIONALLY REQUIRED | If the brcode does not provide an amount, this parameter is mandatory, else it is optional. Example: 23456 (R$ 234,56). |
| `rules` | OPTIONAL | List of rules for modifying brcodePayment behavior. Example: ``` [{"key": "resendingLimit", "value": 5}] ``` |
| `scheduled` | OPTIONAL | Schedule the payment for a specific date. Default value is the current day. |
| `tags` | OPTIONAL | Array of strings to tag the entity for future queries. All tags will be converted to lowercase. |

**Request**

```python
import starkbank

payments = starkbank.brcodepayment.create([
    starkbank.BrcodePayment(
        brcode="00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF",
        tax_id="012.345.678-90",
        scheduled="2021-01-13",
        description="this will be fast",
        tags=["pix", "qrcode"],
        rules=[
            starkbank.brcodepayment.Rule(key="resendingLimit", value=5)
        ]
    )
])

for payment in payments:
    print(payment)
```

**Response**

```python
BrcodePayment(
    amount=0,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2021-01-03 18:36:18.574799,
    description=this will be fast,
    fee=0,
    id=5717797661310976,
    name=None,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    scheduled=2021-01-13 10:00:00,
    status=creating,
    tags=['pix', 'qrcode'],
    tax_id=***.345.678-**,
    transaction_ids=[],
    type=dynamic,
    updated=2021-01-03 18:36:18.574815
)
```

### List Brcode Payments

`GET /v2/brcode-payment`

Get a list of non-deleted brcodes in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**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. Our SDKs handle this for you. |
| `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 brcode payments by the specified status. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

payments = starkbank.brcodepayment.query(
    after="2021-01-01",
    before="2021-01-30"
)

for payment in payments:
    print(payment)
```

**Response**

```python
BrcodePayment(
    amount=0,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2021-01-03 18:36:18.574799,
    description=this will be fast,
    fee=0,
    id=5717797661310976,
    name=None,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    scheduled=2021-01-13 10:00:00,
    status=creating,
    tags=['pix', 'qrcode'],
    tax_id=***.345.678-**,
    transaction_ids=[],
    type=dynamic,
    updated=2021-01-03 18:36:18.574815
)
```

### Get a Brcode Payment

`GET /v2/brcode-payment/:id`

Get a single brcode by its id.

**Parameters**

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

**Request**

```python
import starkbank

payment = starkbank.brcodepayment.get("5717797661310976")

print(payment)
```

**Response**

```python
BrcodePayment(
    amount=0,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2021-01-03 18:36:18.574799,
    description=this will be fast,
    fee=0,
    id=5717797661310976,
    name=None,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    scheduled=2021-01-13 10:00:00,
    status=creating,
    tags=['pix', 'qrcode'],
    tax_id=***.345.678-**,
    transaction_ids=[],
    type=dynamic,
    updated=2021-01-03 18:36:18.574815
)
```

### Update a Brcode Payment

`PATCH /v2/brcode-payment/:id`

Update a single brcode payment, if it hasn't been paid yet.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the brcode payment entity. |
| `status` | OPTIONAL | This can be used to cancel the payment by passing "canceled" as the status patch. |

**Request**

```python
import starkbank

payment = starkbank.brcodepayment.update("5717797661310976", status="canceled")

print(payment)
```

**Response**

```python
BrcodePayment(
    amount=0,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2021-01-03 18:36:18.574799,
    description=this will be fast,
    fee=0,
    id=5717797661310976,
    name=None,
    rules=[
        Rule(
            key=resendingLimit,
            value=5
        )
    ],
    scheduled=2021-01-13 10:00:00,
    status=canceled,
    tags=['pix', 'qrcode'],
    tax_id=***.345.678-**,
    transaction_ids=[],
    type=dynamic,
    updated=2021-01-03 18:36:18.574815
)
```

### Get a Brcode Payment PDF

`GET /v2/brcode-payment/:id/pdf`

Get a brcode payment PDF receipt. You can only get a receipt for payments whose status are either success, processing or created.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the brcode payment entity |

**Request**

```python
import starkbank

pdf = starkbank.brcodepayment.pdf("5717797661310976")

with open("brcode-payment.pdf", "wb") as file:
    file.write(pdf)
```

### List Brcode Payment Logs

`GET /v2/brcode-payment/log`

Get a paged list of all brcode payment logs. A log tracks a change in the payment entity according to its life cycle.

**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. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. |
| `paymentIds` | OPTIONAL | Array of payment ids linked to the desired logs. |
| `types` | OPTIONAL | Filters logs by log types. |

**Request**

```python
import starkbank

logs = starkbank.brcodepayment.log.query(
    after="2021-01-01",
    before="2021-01-30",
    payment_ids=["5717797661310976"]
)

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

**Response**

```python
Log(
    created=2021-01-03 18:36:18.966033,
    errors=[],
    id=5172860540682240,
    payment=BrcodePayment(
        amount=0,
        brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
        created=2021-01-03 18:36:18.574799,
        description=this will be fast,
        fee=0,
        id=5717797661310976,
        name=None,
        rules=[
            Rule(
                key=resendingLimit,
                value=5
            )
        ],
        scheduled=2021-01-13 10:00:00,
        status=canceled,
        tags=['pix', 'qrcode'],
        tax_id=***.345.678-**,
        transaction_ids=[],
        type=dynamic,
        updated=2021-01-03 18:36:18.574815
    ),
    type=failed
)
```

### Get a Brcode Payment Log

`GET /v2/brcode-payment/log/:id`

Get a single brcode payment 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 starkbank

log = starkbank.brcodepayment.log.get("5172860540682240")

print(log)
```

**Response**

```python
Log(
    created=2021-01-03 18:36:18.966033,
    errors=[],
    id=5172860540682240,
    payment=BrcodePayment(
        amount=0,
        brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
        created=2021-01-03 18:36:18.574799,
        description=this will be fast,
        fee=0,
        id=5717797661310976,
        name=None,
        rules=[
            Rule(
                key=resendingLimit,
                value=5
            )
        ],
        scheduled=2021-01-13 10:00:00,
        status=canceled,
        tags=['pix', 'qrcode'],
        tax_id=***.345.678-**,
        transaction_ids=[],
        type=dynamic,
        updated=2021-01-03 18:36:18.574815
    ),
    type=failed
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkbank.com/api/v2/brcode-payment-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/brcode-payment-node.md)
- [PHP](https://docs.starkbank.com/api/v2/brcode-payment-php.md)
- [Java](https://docs.starkbank.com/api/v2/brcode-payment-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/brcode-payment-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/brcode-payment-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/brcode-payment-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/brcode-payment-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/brcode-payment-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/brcode-payment-curl.md)