Using 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 instance: when making a purchase at an online store, the dynamic QR code can include 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 PSPs, this guide will focus on the use of Dynamic QR code.

Generating a new Dynamic QR code

When generate a new dynamic QR code, there are 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 and name of the user that wants to pay the QR code.

• Expiration Date Time: date when you want the QR code to expire, in ISO 8601 format using field expiration_datetime.

  • The default value is 1 day.

  • The minimum configurable expiration time is 5 minutes.

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

POST: https://api.sandbox.trio.com.br/banking/cashin/pix/qrcodes

{
  "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_datetime": "2023-10-04T20:00:00.000000Z",
  "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-04T20:00:00.000000Z",
    "external_id": "01HBSXY7GN8V6NHJ51Z0NX8QK9",
    "hash": "00020101021126640014br.gov.bcb.pix0114041715452853610224018afba3-4924-6ed6-7847-520400005303986540412.05802BR5907Capstan6008Curitiba61088025010462070503***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 to your users two payment methods for a QR Code:

1. Using the "Copy and Paste": send the generated hash to 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.

Document Lifecycle

Each document that is processed by Trio generates and sequence of stages that represent the evolution of the transaction in our system:

• Created - we receive the transaction and enqueue for processing

• Registering - we start to process the settlement

• Settled - transaction was successfully processed and settled, the balance is available in your account, this is a final stage

• Failed - transaction was refused by Trio due to compliance rules, this is a final stage Follow a diagram that represents the flow:

Deposit with QR code flow

Webhook events

To avoid overcommunication, we only send asynchronous communication using webhooks for the final stages.

Settled

This event will be triggered only if the user pays the QR code. We'll create a collecting document that represents the pay-in transaction and notify you through webhooks with the category collecting_document and type settled.

Webhook example

Failed

This event will be triggered only if the user pays the QR code, but the transaction was refused. We'll create a collecting document that represents pay-in transaction and notify you through webhooks with the category collecting_document and type failed.

Webhook example

To achieve both Settled and Failed transaction states, please refer to the next guides: Simulating Deposit Success and Simulating Deposit Failures.