Cash in

Cash-in transactions are the deposits that arrive in your bank accounts, for example a dynamic QR code that a payer scans and pays. This tutorial creates your first dynamic QR code in the sandbox and walks through the response. For the other ways to receive money, see the Receivables overview.

Before you start

You need:

An API credential. See Creating your first API credential.
The id of the bank account that receives the funds. List your accounts with GET /v2/bank_accounts.

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

Create the QR code

Send a POST to the Create a dynamic QR code endpoint:

POST /v2/in/pix/qrcodes

{
  "bank_account_id": "0196346c-ffa2-e861-be85-3c2736d0005f",
  "counterparty": {
    "tax_number": "12385407400",
    "name": "Payer Name"
  },
  "amount": 320000,
  "external_id": "{{$randomUUID}}",
  "description": "Pay in Sandbox",
  "options": {
    "allow_change_the_amount_on_payment": false,
    "show_qrcode_image": false
  }
}

Field	Required	Description
`bank_account_id`	Yes	Bank account that receives the funds. Use the `id` returned by `GET /v2/bank_accounts`.
`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 own identifier for the transaction, used for reconciliation and to match webhook events.
`description`	No	Free-text description of the charge.
`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.

Coming from V1? allow_change_the_amount_on_payment and show_qrcode_image now live inside options and both are required. The response has no stages, virtual_account_id or pix_key_id.

Read the response

{
  "data": {
    "id": "0192bebb-fbdb-b6f3-6be1-7153e373b609",
    "status": "created",
    "description": "Pago a trio.com.br",
    "hash": "00020101021226790014br.gov.bcb.pix2557brcode-h.trio.com.br/check/cob/01JAZBQYYVPVSPQRBHAFHQ7DG95204000053039865802BR5906BRCODE6008Curitiba62070503***6304736E",
    "amount": {
      "currency": "BRL",
      "amount": 320000
    },
    "external_id": "49d754c2-ac14-4219-bbe4-3e78e9ab8067",
    "bank_account_id": "0196346c-ffa2-e861-be85-3c2736d0005f",
    "counterparty": {
      "id": "0013ebcc-d457-e4f8-0079-4e996002d082",
      "bank_accounts": []
    },
    "fee": {
      "amount": 0,
      "currency": "BRL"
    },
    "options": {
      "allow_change_the_amount_on_payment": false
    },
    "origin": {
      "id": "01929738-5e7e-46d1-d8af-ea9629302b80",
      "type": "api_client"
    },
    "expiration_datetime": null,
    "inserted_at": "2024-10-24T13:34:03.739892Z",
    "updated_at": "2024-10-24T13:34:03.739892Z"
  }
}

The fields you use most:

Field	Description
`id`	Identifier of the QR code. Use it to read, update or fetch the image of the code.
`status`	`created` on creation. The QR code moves to `settled` once paid.
`hash`	The BR code (the Pix copy-and-paste code) to share with the payer.
`amount`, `fee`	Money objects with the amount and the optional fee in cents.
`counterparty.id`	Identifier Trio assigned to the payer.
`origin`	Who created the QR code, here your API client.

If you did not request the image, share the hash with the payer: it is the BR code they paste into their banking application. To render the image on your side, encode the hash as a QR code, or fetch it ready-made from GET /v2/in/pix/qrcodes/{id}/image, which returns it in Base64.

What happens next

Once the QR code is paid, the deposit shows up as an in document with its own status and stages. List deposits with GET /v2/documents/in or read one with GET /v2/documents/in/{id}, and follow each status change through webhook events. The Document lifecycle guide describes the statuses.

Next steps

QR code types: static, dynamic and dynamic-with-due-date codes.
Simulate a successful deposit: pay your QR code in the sandbox.
Fees and Split payments: charge extra or distribute the amount.
Create a boleto: receive by boleto instead of Pix.

Onboarding

Receivables

Payments

Operations

Trio MCP

Trio SDK

Before you start

Create the QR code

Read the response

What happens next

Next steps

​Before you start

​Create the QR code

​Read the response

​Share the BR code

​What happens next

​Next steps

Before you start

Create the QR code

Read the response

Share the BR code

What happens next

Next steps