QR code types

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.

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. 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, as shown below. After creation, PUT /v2/in/pix/qrcodes/{id} 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.

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.

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.
`splits`	No	Distributes the amount among split recipients. See Split payments.

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

{
  "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:

{
  "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.

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, 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 and follow through webhook events. 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).

See the Document lifecycle guide for the full list of V2 statuses.

Next steps

Cash in: a step-by-step walk through your first dynamic QR code.
Simulate a successful deposit: pay the code in the sandbox.
Pix Automático: recurring charges authorized once by the payer.
Create a boleto: the same due-date rules on a boleto.

Onboarding

Receivables

Payments

Operations

Trio MCP

Trio SDK

Static QR code

Dynamic QR code

Dynamic QR code with due date

Which type to use

Generate a dynamic QR code

Response

Deliver the code to the payer

Follow the payment

Next steps

​Static QR code

​Dynamic QR code

​Dynamic QR code with due date

​Which type to use

​Generate a dynamic QR code

​Response

​Deliver the code to the payer

​Follow the payment

​Next steps

Static QR code

Dynamic QR code

Dynamic QR code with due date

Which type to use

Generate a dynamic QR code

Response

Deliver the code to the payer

Follow the payment

Next steps