# Pix QR Code

Learn how to receive Pix payments using Dynamic QR Codes on the Stark Bank platform.

A Dynamic QR Code (also called a Dynamic BR Code) is a Pix QR Code whose payment information is fetched in real time. This means you can set amounts, add tags, and control expiration — all from a single generated code.

When someone scans and pays your QR Code, Stark Bank automatically creates a Deposit in your account. You can track deposits via webhooks or by querying the API.

For a complete Pix QR Code solution with built-in conciliation, check the Invoice Get Started.

NOTE: Read Core Concepts before continuing this guide.

**RESOURCE SUMMARY**

Dynamic BR CodeThe QR Code you generate for your customer to scan and pay.DepositThe payment received in your account after a QR Code is paid.

## Setup

For each environment (Sandbox or Production):

1. Create an account at Stark Bank.

2. Create a webhook with the following subscription to receive events at your desired URL:

deposit

2.1. Via Internet Banking:

Integrations > Webhook > New Webhook

2.2. Via API:

Use the POST /webhook route to create the webhook

## Payment Flow

The QR Code payment flow works in three steps:

1. Create a Dynamic BR Code: Your server calls the Stark Bank API to generate a QR Code with the desired amount, expiration, and optional tags or rules.

2. Display the QR Code: Use the returned pictureUrl to display the QR Code image to your customer

3. Copy and Paste the QR Code: Use the id to allow your customer to copy and paste it and pay the QR Code in their bank account

4. Receive the Deposit: Once the customer pays, Stark Bank creates a Deposit in your account. The deposit's tags field will contain "dynamic-brcode/{uuid}" linking it back to the original QR Code for easy reconciliation.

## Sandbox

The Sandbox environment simulates the full QR Code payment flow — creation, payment, and deposit — without real money. Use it to test your integration before going live.

Sandbox vs Production: Stark Bank uses separate workspaces for each environment, each with its own URL and API keys. Changes in one environment don't affect the other.

If you don't have a Sandbox workspace yet, create one here:

Create a Workspace in Sandbox

## Dynamic BR Code Overview

A Dynamic BR Code is a simple Pix QR Code that allows your customer to pay it once. It allows you to set amounts, expiration times, tags, and payer restrictions. Unlike static QR Codes, the payment information is fetched in real time when the payer scans it.

### The Dynamic BR Code object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `amount` | INTEGER | Amount in cents to be received. Example: 100 (R$1.00). |
| `expiration` | INTEGER | Time in seconds from creation until expiration. After expiration, the QR Code cannot be paid. Default: 3600 (1 hour). |
| `pictureUrl` | STRING | URL of the QR Code image. Display this to your customer so they can scan it. |
| `tags` | LIST OF STRINGS | Tags associated with the Dynamic BR Code. Useful for organizing and filtering. |
| `rules` | LIST OF OBJECTS | List of rules for modifying Dynamic BR Code behavior (e.g., restricting which tax IDs can pay). |
| `uuid` | STRING | Unique UUID for the Dynamic BR Code. Used to retrieve the QR Code and to link it to the resulting Deposit. |
| `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". |

### Creating a Dynamic BR Code

To generate a QR Code, create a Dynamic BR Code with the desired amount in cents (4000 = R$40,00).

The response includes a pictureUrl you can display to your customer and a uuid you can use for reconciliation.

### Setting an Expiration

By default, a Dynamic BR Code expires in 1 hour (3600 seconds). You can customize this by passing the expiration parameter in seconds.

After the QR Code expires, it can no longer be paid.

### Adding Tags

Tags help you organize and filter your QR Codes. Add any labels that make sense for your business — for example, an order ID or customer reference.

All tags are automatically converted to lowercase.

### Restricting Payers

You can restrict who can pay a QR Code by passing rules. The allowedTaxIds rule limits payment to specific CPFs or CNPJs.

If anyone other than the allowed payers tries to scan and pay, the transaction will be rejected.

### Listing Dynamic BR Codes

You can list all Dynamic BR Codes that match your filters. Use the after and before parameters to filter by creation date.

### Getting a Dynamic BR Code

You can retrieve a Dynamic BR Code by its uuid to check its current amount, or any other attribute.

## Deposit Overview

A Deposit is automatically created when someone pays your Dynamic BR Code. It represents the Pix payment received in your Stark Bank account.

Each Deposit created from a QR Code payment will have a tag in the format "dynamic-brcode/{uuid}", where {uuid} is the UUID of the Dynamic BR Code that was paid. Use this tag to match deposits to the original QR Codes.

### The Deposit object

**Parameters**

| Name | Type | Description |
| --- | --- | --- |
| `id` | STRING | Unique id for the deposit. |
| `amount` | INTEGER | Deposit amount in cents. |
| `name` | STRING | Payer full name. |
| `taxId` | STRING | Payer CPF or CNPJ. |
| `bankCode` | STRING | Payer bank code or ISPB. |
| `branchCode` | STRING | Payer bank branch. |
| `accountNumber` | STRING | Payer bank account number. |
| `accountType` | STRING | Payer bank account type. |
| `type` | STRING | Type of the deposit. |
| `fee` | INTEGER | Fee charged in cents. |
| `tags` | LIST OF STRINGS | Tags associated with the deposit. QR Code payments include a tag like "dynamic-brcode/{uuid}". |
| `transactionIds` | LIST OF STRINGS | Ledger transaction IDs linked to the deposit. |
| `status` | STRING | Current deposit status. Options: "created", "void". |
| `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". |

### Deposit Status

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

| Status | Description |
| --- | --- |
| Created | You received a deposit in your account. |
| Voided | You fully returned the deposit. |

### The Deposit Logs

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

A Deposit can be either partially or fully reversed back to its payer. Multiple reversals can be made for the same deposit and each time, the following flow of logs will occur:

| Log type | Status | Description |
| --- | --- | --- |
| Created | Created | The Deposit was successfully received in your Stark Bank account. |
| Credited | Created | The Deposit payment was credited to your account. |
| Voided | Voided | The Deposit was fully returned. |
| Reversing | Created | A reversal for the Deposit is being processed. |
| Sending | Created | The reversal is being sent to the banking network. |
| Sent | Created | The reversal was sent to the banking network. |
| Failed | Created | The reversal failed. |
| Reversed | Created | The Deposit was partially or fully reversed to the payer. |
| Refunded | Created | The reversal was refunded back to you after failing. |

### Listing Deposits

You can list and filter deposits to find payments received from your QR Codes.

Use the tags parameter to filter deposits by a specific Dynamic BR Code UUID — for example, filtering by "dynamic-brcode/80b0688d05934971a6b8ecd86cde69f2" will return only the deposit created when that QR Code was paid.

**Response**

```python
Deposit(
    account_number=1010101010101010,
    account_type= "payment",
    amount=4000,
    bank_code=20018183,
    branch_code=0001,
    created=2023-02-06 22:14:58.555321,
    fee=0,
    id=4638572095847362,
    name=Jon Snow,
    status=created,
    tags=['dynamic-brcode/80b0688d05934971a6b8ecd86cde69f2'],
    tax_id=012.345.678-90,
    transaction_ids=['6532871094857362'],
    type=pix,
    updated=2023-02-06 22:14:58.555321
)
```

### Getting a Deposit

You can retrieve a single Deposit by its ID to check its amount, status, payer information, and tags.

### Reversing Partially a Deposit

To partially reverse a Deposit, you need to PATCH the deposit amount to a lower value. The difference between the original amount and the new amount will be reversed to the payer.

For example, if a Deposit was credited with an amount of 10000 (R$ 100.00) and you patch the amount to 3000 (R$ 30.00), it means you reversed 7000 (R$ 70.00) back to the payer.

While the reversal is being processed, the deposit status remains created.

### Reversing Fully a Deposit

To fully reverse a Deposit, you need to PATCH the deposit amount to 0. This will reverse the entire amount back to the payer.

For example, if a Deposit was credited with an amount of 10000 (R$ 100.00) and you patch the amount to 0, the full 10000 (R$ 100.00) will be reversed to the payer.

After the full reversal is completed, the deposit status changes to voided.

### Receiving Deposit Webhooks

After setting up a webhook subscription for deposit, Stark Bank will send a POST request to your registered URL every time a Deposit is created or updated.

Use the tags field in the webhook payload to match the deposit to the original Dynamic BR Code. The tag below links the deposit back to the QR Code that generated it.

"dynamic-brcode/{uuid}"

---

## Other Languages

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