> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trio.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# QR code types

> Choose between static, dynamic and dynamic-with-due-date Pix QR codes, and generate a dynamic QR code.

Pix QR codes are the fastest way to collect a payment: the payer scans the code or pastes the BR code (the Pix copy-and-paste code) into their banking application. The API offers three types; this guide explains when to use each and how to generate a dynamic QR code, the type most online merchants and payment service providers rely on. For the full cash-in picture, see the [Receivables overview](https://docs.trio.com.br/v2/guides/receivables/overview.md).

## Static QR code

A static QR code carries fixed payment information that does not change between transactions. Use it for recurring or standardized charges where the amount and payment details stay the same:

* Fixed and reusable payment information.
* Suitable for recurring collections.
* Can be permanently displayed or printed.

Create one with [`POST /v2/in/pix/qrcodes/static`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/pix/qrcode-static/post). Send `amount: 0` for an open-amount code, where the payer chooses the amount.

## Dynamic QR code

A dynamic QR code is generated for one transaction and carries that transaction's information. Use it for e-commerce platforms, payment service providers and automated payment flows:

* Unique transaction information for each payment.
* Supports your own identifiers and metadata.
* Enables automated reconciliation and tracking.

Create one with [`POST /v2/in/pix/qrcodes`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/pix/qrcode-dynamic/post), as shown [below](#generate-a-dynamic-qr-code). After creation, [`PUT /v2/in/pix/qrcodes/{id}`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/pix/qrcode-dynamic/update) updates the `amount`, `expiration_datetime` or `fee` of an existing dynamic QR code and returns `204 No Content`.

## Dynamic QR code with due date

A dynamic QR code with due date is a dynamic QR code that carries a due date and the payment rules attached to it: fine, interest, rebate and discount. Use it when the charge behaves like an invoice. Create one with [`POST /v2/in/pix/qrcodes/with_due`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/pix/qrcode-with-due/post).

## Which type to use

| Type | Create endpoint | Use it when |
| - | - | - |
| Static QR code | `POST /v2/in/pix/qrcodes/static` | The same code is reused, for example on a counter or a printed flyer. |
| Dynamic QR code | `POST /v2/in/pix/qrcodes` | Each charge is unique and you reconcile it automatically. |
| Dynamic QR code with due date | `POST /v2/in/pix/qrcodes/with_due` | The charge has a due date with fine, interest, rebate or discount rules. |

## Generate a dynamic QR code

All examples use the sandbox base URL `https://api.sandbox.trio.com.br`.

```http theme={null}
POST /v2/in/pix/qrcodes
```

| Field | Required | Description |
| - | - | - |
| `bank_account_id` | Yes | Bank account that receives the funds. |
| `counterparty` | No | Payer information. When sent, `tax_number` and `name` are required. |
| `amount` | Yes | Amount in cents (BRL 100.00 = `10000`). |
| `external_id` | No | Your internal transaction reference. |
| `description` | No | Free-text description of the charge. |
| `expiration_datetime` | No | When the QR code expires, in ISO 8601 format. |
| `options.allow_change_the_amount_on_payment` | Yes | Whether the payer may change the amount when paying. |
| `options.show_qrcode_image` | Yes | When `true`, the response also carries the QR code image in Base64. |
| `options.fee` | No | Extra amount in cents charged on top of `amount`. See [Fees](https://docs.trio.com.br/v2/guides/receivables/fees.md). |
| `splits` | No | Distributes the amount among split recipients. See [Split payments](https://docs.trio.com.br/v2/guides/receivables/split-payments.md). |

The default expiration time is 1 day, and the minimum allowed expiration time is 5 minutes.

Example request:

```json theme={null}
{
  "bank_account_id": "018af380-ced7-436a-b118-1cf3bd54243f",
  "counterparty": {
    "tax_number": "70004764005",
    "name": "Jhon Doe"
  },
  "amount": 1200,
  "external_id": "01HBSXY7GN8V6NHJ51Z0NX8QK9",
  "description": "Pay in Sandbox",
  "expiration_datetime": "2023-10-04T20:00:00.000000Z",
  "options": {
    "allow_change_the_amount_on_payment": false,
    "show_qrcode_image": false
  }
}
```

### Response

On success the API returns `201 Created` with the QR code:

```json theme={null}
{
  "data": {
    "id": "018afba3-491b-4fd2-e8e2-edee87faab18",
    "status": "created",
    "description": "Pay in Sandbox",
    "hash": "00020101021126640014br.gov.bcb.pix0114041715452853610224018afba3-4924-6ed6-7847-520400005303986540412.05802BR5907Capstan6008Curitiba61088025010462070503***63043277",
    "amount": {
      "amount": 1200,
      "currency": "BRL"
    },
    "external_id": "01HBSXY7GN8V6NHJ51Z0NX8QK9",
    "bank_account_id": "018af380-ced7-436a-b118-1cf3bd54243f",
    "counterparty": {
      "id": "018af3e0-63b4-d4fc-9c84-459314081895",
      "bank_accounts": []
    },
    "fee": {
      "amount": 0,
      "currency": "BRL"
    },
    "options": {
      "allow_change_the_amount_on_payment": false
    },
    "origin": {
      "id": "018af380-789f-4c52-fb8a-8160ad66182a",
      "type": "api_client"
    },
    "expiration_datetime": "2023-10-04T20:00:00.000000Z",
    "inserted_at": "2023-10-04T17:01:36.923773Z",
    "updated_at": "2023-10-04T17:01:36.923773Z"
  }
}
```

The payer is the nested `counterparty` object and the creator is the nested `origin` object. `counterparty.bank_accounts` lists the bank accounts the payment must come from and is empty when any account is accepted. `image` is returned only when `options.show_qrcode_image` is `true`.

> [!NOTE]
>
> **Coming from V1?** The response no longer carries `virtual_account_id`, `entity_id`, `pix_key_id` or `timestamp`. Timestamps are `inserted_at` and `updated_at`, and `allow_change_the_amount_on_payment` lives inside `options`.

### Deliver the code to the payer

* **BR code**: send the `hash` so the payer pastes it into their banking application.
* **QR code image**: render the `hash` as a QR code image for the payer to scan. You can also ask the API for the image, either with `options.show_qrcode_image: true` on creation or later with [`GET /v2/in/pix/qrcodes/{id}/image`](https://docs.trio.com.br/v2/api-reference/banking-api/receivables/pix/qrcode-dynamic/get-image), which returns it in Base64.

## Follow the payment

The QR code itself has a `status` of `created`, `settled` or `deleted`. Once paid, the deposit becomes an in document that you list with [`GET /v2/documents/in`](https://docs.trio.com.br/v2/api-reference/banking-api/documents/receivables/list-receivables) and follow through [webhook events](https://docs.trio.com.br/v2/webhooks/events/overview.md). Each transaction progresses through the following stages:

* `created`: transaction received and queued for processing.
* `registering`: transaction is being processed.
* `settled`: transaction successfully processed and settled (final state).
* `failed`: transaction refused due to validation or compliance rules (final state for cash out).

![Transaction flow](https://mintcdn.com/trio-372e8dab/x8bS2HzNhei2b1vu/images/image-\(29\).png?fit=max\&auto=format\&n=x8bS2HzNhei2b1vu\&q=85\&s=f4af44cc2e6cb1a72353845fa588b05b)

See the [Document lifecycle](https://docs.trio.com.br/v2/guides/pix/document-lifecycle.md) guide for the full list of V2 statuses.

## Next steps

* [Cash in](https://docs.trio.com.br/v2/guides/receivables/cash-in.md): a step-by-step walk through your first dynamic QR code.
* [Simulate a successful deposit](https://docs.trio.com.br/v2/guides/receivables/simulating-deposit-success.md): pay the code in the sandbox.
* [Pix Automático](https://docs.trio.com.br/v2/guides/receivables/using-pix-automatic.md): recurring charges authorized once by the payer.
* [Create a boleto](https://docs.trio.com.br/v2/guides/boleto/create-boleto.md): the same due-date rules on a boleto.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.