# Pix QR Code Payment

We provide the convenience of paying Pix QR codes directly from your Stark Bank account.

In the document below, we will detail the processes related to paying Pix QR codes (both static and dynamic) from Stark Bank or other institutions, providing a clear and comprehensive understanding of the operation and how to manage the lifecycle of this resource.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

Brcode PaymentPay Pix QR codes using your Stark Bank balance

## Setup

For each environment: (Sandbox or Production)

1. Create an account at Stark Bank.

2. Create a webhook with the following subscriptions to receive events in your desired URL:

brcode-payment

2.1. Via Internet Banking: 

Integrations > Webhook > New Webhook

2.2. Via API: 

Use the POST /webhook route to create the webhook

## Brcode Payment Overview

Brcode Payment is a resource that can be used to pay Pix QR codes (both static and dynamic) from Stark Bank or other institutions.

To create a Brcode Payment, you need to provide the mandatory parameters: brcode, taxId and description.

Optional parameters include scheduled, tags, and rules.

### The Brcode Payment Object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the brcode payment. |
| `amount` | INTEGER | Amount in cents to be paid. Example: 1000000 (R$10,000.00). |
| `brcode` | STRING | Pix QR code string to be paid. |
| `created` | STRING | Creation datetime. Example: "2020-02-06T16:22:24.664148+00:00". |
| `description` | STRING | Text to be displayed in your statement. |
| `fee` | INTEGER | Fee charged in cents. |
| `name` | STRING | Receiver full name. |
| `rules` | LIST OF OBJECTS | List of rule objects with key and value to modify brcode payment behavior. |
| `scheduled` | STRING | Scheduled date or datetime for the brcode payment. Example: "2020-08-14" or "2020-08-14T15:23:26+00:00". |
| `status` | STRING | Current brcode payment status. Options: "created", "processing", "success", "failed", "canceled". |
| `tags` | LIST OF STRINGS | Tags associated with the brcode payment. |
| `taxId` | STRING | Payment payer CPF or CNPJ. |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the brcode payment. |
| `type` | STRING | Type of the brcode payment. Options: "dynamic", "static". |
| `updated` | STRING | Last update datetime. Example: "2020-02-06T16:22:24.664148+00:00". |

### The Brcode Payment Status

Each Brcode Payment has a status that can change over time according to its life cycle:

| Status | Description |
| --- | --- |
| Created | The Brcode Payment was successfully created in Stark Bank. |
| Processing | The Brcode Payment is being processed by Stark Bank. |
| Success | The Brcode Payment was successfully completed. |
| Failed | The Brcode Payment was unsuccessful. |
| Canceled | The Brcode Payment was canceled before processing. |

### The Brcode Payment Logs

Every time either you or Stark Bank makes a change to a Brcode Payment, we create a Log. Logs are pretty useful for understanding the life cycle of each Brcode Payment and the changes that happened to it. Here you can see the flow of possible logs:

A completed Brcode Payment can be reversed back to its payer. When a reversal occurs, the following flow of logs will happen:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Brcode Payment was successfully created in Stark Bank. |
| Sending | Processing | The Brcode Payment is being sent to the banking network. |
| Success | Success | The Brcode Payment was successfully completed and credited. |
| Failed | Failed | The Brcode Payment was unsuccessful. |
| Canceling | Processing | The Brcode Payment cancellation is being processed. |
| Canceled | Canceled | The Brcode Payment was canceled before processing. |
| Reversing | Success | The Brcode Payment reversal is being processed. |
| Reversed | Success | The Brcode Payment was reversed back to the payer. |

### Creating Brcode Payments

To create a Brcode Payment, fill in the mandatory parameters: brcode, taxId and description.

The brcode parameter must contain a valid Pix QR code string (static or dynamic).

Brcode Payments are available 24/7 and can be scheduled for any date and time.

**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",
        description="this will be fast"
    )
])

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

**Response**

```python
BrcodePayment(
    amount=1000,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2020-02-06 16:22:24.664134,
    description=this will be fast,
    fee=0,
    id=5412038532661248,
    name=Stark Bank S.A. - Instituicao de Pagamento,
    rules=[],
    scheduled=2020-02-07 10:00:00,
    status=created,
    tags=[],
    tax_id=012.345.678-90,
    transaction_ids=[],
    type=dynamic,
    updated=2020-02-06 16:22:24.664134
)
```

### Creating Brcode Payments with scheduled, tags parameters

Scheduled: Schedule the brcode payment for a specific date.

Today is the default.

Brcode Payments are available 24/7 and can be scheduled for any date and time.

Example: "2020-08-14T15:23:26+00:00" or "2020-08-14"

Tags: Array of strings to tag the entity for future queries. All tags will be converted to lowercase. Example: ["pix", "qrcode/1234"]

**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",
        description="this will be fast",
        scheduled="2020-08-14",
        tags=["pix", "invoice/1234"]
    )
])

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

**Response**

```python
BrcodePayment(
    amount=1000,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2020-02-06 16:22:24.664134,
    description=this will be fast,
    fee=0,
    id=5412038532661248,
    name=Stark Bank S.A. - Instituicao de Pagamento,
    rules=[],
    scheduled=2020-08-14 10:00:00,
    status=created,
    tags=['pix', 'invoice/1234'],
    tax_id=012.345.678-90,
    transaction_ids=[],
    type=dynamic,
    updated=2020-02-06 16:22:24.664134
)
```

### Listing Brcode Payments

Get a list of Brcode Payments using filters such as after, before, status and tags to narrow the results.

**Request**

```python
import starkbank

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

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

**Response**

```python
BrcodePayment(
    amount=1000,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2020-04-24 17:49:10.225810,
    description=this will be fast,
    fee=0,
    id=5950134772826112,
    name=Stark Bank S.A. - Instituicao de Pagamento,
    rules=[],
    scheduled=2020-08-14 10:00:00,
    status=processing,
    tags=['pix', 'invoice/1234'],
    tax_id=012.345.678-90,
    transaction_ids=['5991715760504832'],
    type=dynamic,
    updated=2020-04-24 17:49:10.225810
)
```

### Getting a Brcode Payment

Get a single Brcode Payment by its id.

You can use it to check the current status of a Brcode Payment.

**Request**

```python
import starkbank

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

print(payment)
```

**Response**

```python
BrcodePayment(
    amount=1000,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2020-04-24 17:49:10.225810,
    description=this will be fast,
    fee=0,
    id=5950134772826112,
    name=Stark Bank S.A. - Instituicao de Pagamento,
    rules=[],
    scheduled=2020-08-14 10:00:00,
    status=processing,
    tags=['pix', 'invoice/1234'],
    tax_id=012.345.678-90,
    transaction_ids=['5991715760504832'],
    type=dynamic,
    updated=2020-04-24 17:49:10.225810
)
```

### Canceling Brcode Payment

This method will allow the cancellation of a brcode payment.

It's important to note that it's only possible to cancel brcode payments before the start of processing.

**Request**

```python
import starkbank

payment = starkbank.brcodepayment.delete("6693962735681536")

print(payment)
```

**Response**

```python
BrcodePayment(
    amount=1000,
    brcode=00020101021226890014br.gov.bcb.pix2567brcode-h.sandbox.starkinfra.com/v2/ace289aac1ce453b9ca64fb12ec525855204000053039865802BR5925Stark Bank S.A. - Institu6009Sao Paulo62070503***63044DDF,
    created=2020-04-24 17:49:10.225810,
    description=this will be fast,
    fee=0,
    id=6693962735681536,
    name=Stark Bank S.A. - Instituicao de Pagamento,
    rules=[],
    scheduled=2020-08-14 10:00:00,
    status=canceled,
    tags=['pix', 'invoice/1234'],
    tax_id=012.345.678-90,
    transaction_ids=[],
    type=dynamic,
    updated=2020-04-24 17:49:10.225810
)
```

### Receiving Brcode Payment Webhook

After creation, you can use asynchronous Webhooks to monitor status changes of the entity. The Brcode Payment will follow the following life cycle:

Every time we change a Brcode Payment, we create a Log. Logs are pretty useful for understanding the life cycle of each Brcode Payment. Whenever a new Log is created, we will fire a Webhook to your registered URL.

NOTE: Check the Webhook Get Started for more details on how to receive and process Webhook events.

NOTE: A brcode-payment subscription is required to receive this event.

---

## Other Languages

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