Pay-in using a QR code

The use of QR codes is one way to facilitate and expedite transactions. There are two main categories of QR codes in Pix: Dynamic QR code and Static QR code. Let's understand the difference between them:

Static QR Code: The static QR code contains fixed information that does not change over time or transactions. It is useful for receiving payments for a specific amount and/or standardized information. For example, a merchant can generate a static QR code to receive payments for a fixed amount for a product or service. This QR code will maintain the same payment information, such as the Pix key and the amount, regardless of how many times it is scanned.

Dynamic QR Code: The dynamic QR code contains variable information that can be updated for each transaction. It is especially useful for transactions of different amounts or when specific information needs to be included for each payment. For example, when making a purchase at an online store, the dynamic QR code can include information about the amount to be paid and other relevant details for that specific transaction. Each time the dynamic QR code is scanned, it can display a different value and unique details for that transaction.

Since most of our customers are online merchants and PSP's the guide will focus on the use of Dynamic QR code.

Generating a new Dynamic QR code

When generate a new dynamic QR code, there some important parameters that you need to pay attention:

  • Virtual Account ID: virtual account that will receive and hold the money.
  • External ID: reference of your transaction in our system.
  • Amount: amount of the transaction, always represented in cents.
  • Counterparty: tax_number or name of the user that wants to pay the QR code.
  • Expiration Date: date when to you want the QR code to expire in the ISO 8601 format. The default value is 7 days.

To generate the QR code, send a POST request to the create QR code endpoint using this payload:


  "virtual_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b",
  "counterparty": {
    "tax_number": "70004764005",
    "name": "Jhon Doe"
  "amount": 1200,
  "external_id": "01HBSXY7GN8V6NHJ51Z0NX8QK9",
  "description": "Pay in Sandbox",
  "expiration_date": "",
  "options": {
    "allow_change_the_amount_on_payment": false,
    "show_qrcode_image": false

If everything is OK, you will receive a 201 response with a payload like this:

  "data": {
    "allow_change_the_amount_on_payment": false,
    "amount": {
      "amount": 1200,
      "currency": "BRL"
    "bank_account_id": "018af380-ced7-436a-b118-1cf3bd54243f",
    "counterparty_id": "018af3e0-63b4-d4fc-9c84-459314081895",
    "description": "Pay in Sandbox",
    "entity_id": "018af380-789f-4c52-fb8a-8160ad66182a",
    "expiration_datetime": "2023-10-11T17:01:36.923652Z",
    "external_id": "01HBSXY7GN8V6NHJ51Z0NX8QK9",
    "hash": "***63043277",
    "id": "018afba3-491b-4fd2-e8e2-edee87faab18",
    "pix_key_id": "018af380-eb7e-93a9-4b9f-c08af1d7772f",
    "status": "created",
    "timestamp": "2023-10-04T17:01:36.923773Z",
    "virtual_account_id": "018af380-cedc-3a53-29c0-e329bf0e109b"

You can offer for your users to methods to pay this QR code:

  1. Using the "Copy and Paste": send the generated hash to the the user. They will be able to paste the hash in their bank app to complete de payment.
  2. QR code image: generate a QR code with the hash parameter and show to the user. They will be able to scan the QR code with their bank app to complete the payment.

Once the user pay the QR code, Trio will receive the money, creates a collecting document that represents the pay-in transaction and we will notify you using a webhook with category collecting_document and type settled:

  "ref_id": "018ae1cc-5497-2935-77b6-6ed4dc71c37f",
  "category": "collecting_document",
  "type": "settled",
  "data": {
    "amount": {
      "amount": 1200,
      "currency": "BRL"
    "bank_account_id": "0189d6b1-2e56-7a99-b73f-d08f71352dc4",
    "company_id": "0189d6b0-cd94-24d3-dee4-bb07aed88566",
    "counterparty_bank_account_id": "0189d6b1-465f-422e-6268-84d0bc1e2bbc",
    "counterparty_id": "0189d6b1-2f81-e48f-111b-fe818587ae32",
    "description": "Payment pix sandbox",
    "end_to_end_id": "01HBGWRN4Q5W5PFPAY64XHR77X",
    "entity_id": "0189d6b1-2e33-98cb-5548-3c17d2ef63e0",
    "external_id": "colibrix10",
    "id": "018ae1cc-5497-2935-77b6-6ed4dc71c37f",
    "marked_for_automatic_refund": false,
    "receipt_url": "",
    "reconciliation_id": "01HBGW0SJQ795ZR6BH78EJ0J0Q",
    "ref_id": "018ae1c0-6657-a51f-862f-9bf73929fa42",
    "ref_type": "pix_qrcode",
    "status": "settled",
    "transaction_date": "2023-09-29T16:36:19.223179Z",
    "type": "pix",
    "virtual_account_id": "0189d6b1-2f3d-522e-9532-ad346739c419"
  "timestamp": "2023-09-29T16:36:20.406192Z",
  "company_id": "0189d6b0-cd94-24d3-dee4-bb07aed88566"

Within the webhook, you'll have access to all information about the collecting document (pay-in). For example:

  • represents the ID from the collecting document, you can query the details using the collecting document GET endpoint.
  • data.counterparty_id represents the ID from the user that paid the QR code, you can access the details using the counterparty GET endpoint.
  • data.ref_id represents the the QR code linked with the pay-in.
  • data.external_id is the external ID that was informed in the QR code, with that information you can link the transaction on you side.
  • data.marked_for_automatic_refund will be trueif the transaction was identified as a risky or don't met our compliance standards otherwise will be false. More details of our automatic refund feature.

Congratulations, you have completed your first pay-in using QR code with Trio 🍻. If you have any questions, please drop us a message at [email protected].