Guides

Payout using a QRCode (V1)

Suggest Edits

A QRCode in the context of Pix represents a pix key, which in turn represents a bank account in the Pix arrangement. A string that represents a QRCode is called a BRCode hash.

The only information you need from the customer is the BRCode hash. A hash is a long string of characters that every BRCode follows a pattern similar to:

00020101021126640014br.gov.bcb.pix0114570885548506770224018e6143-8855-0b6c-2073-52040000530398654040.015802BR5913Minha Empresa6008Curitiba61088025010462070503***63045264

Generating a new Payout

To generate a new payout in V1 using a QRCode, you must go through two steps:

  • Check your BRCode using the Check BRCode endpoint. By making this request, you will receive information regarding the tax number involved, so you can decide whether or not the tax number is the one you desire to make a pay-out to.
  • If you decide that it is valid, you can make a pay-out using the Pix V1 endpoint

Let's do both requests to see what you can expect from their respective responses.

Checking a QRCode

When checking a pix brcode, there are some parameters that you will need to pay attention to (* for required fields):

  • Entity ID: the unique identifier for the entity_id that will hold the checked QRCode information.
  • Hash: the value of the QRCode you desire to check. e.g: "+5583988720998"

POST /banking/cashout/pix/brcodes/check

{
    "entity_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
    "hash": "00020101021126640014br.gov.bcb.pix0114570885548506770224018e6143-8855-0b6c-2073-52040000530398654040.015802BR5913Minha Empresa6008Curitiba61088025010462070503***63045264"
}

If the key is a valid existing one, you will receive a 200 response akin to:

{
    "data": {
        "counterparty": {
            "bank_account": {
                "account_digit": "7",
                "account_number": "73451",
                "account_type": "checking",
                "bank_ispb": "36305779",
                "bank_number": "425797",
                "branch": "1685",
                "id": "018e5bd3-6f40-718b-d01c-9ee5d45032f7",
                "inserted_at": "2024-03-20T12:26:07.040509Z",
                "updated_at": "2024-03-20T12:26:07.040509Z"
            },
            "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
            "external_id": "018e5bd1-1fe9-ec37-8642-c2b2959ff317",
            "id": "018e5bd1-2007-c6b1-9591-8d554306c381",
            "inserted_at": "2024-03-20T12:23:35.692818Z",
            "ledger_type": "customer",
            "maximum_amount": null,
            "maximum_transactions": null,
            "name": "Farrell-McDermott LLC",
            "tax_number": "57088554850677",
            "updated_at": "2024-03-20T12:23:35.692818Z"
        },
        "description": null,
	      "due_date": "2024-03-24",
        "entity_id": "018e5bd0-91b9-c70c-1970-54a94d946326",
      	"expiration_date": "2024-03-24T13:46:39.569934Z",
      	"hash": "00020101021126640014br.gov.bcb.pix0114570885548506770224018e6143-8855-0b6c-2073-52040000530398654040.015802BR5913Minha Empresa6008Curitiba61088025010462070503***63045264",
        "id": "018e612f-3740-96ec-9ecf-de48c743a988",
        "inserted_at": "2024-03-21T13:24:28.096836Z",
      	"key": "57088554850677",
        "type": "tax_number",
        "updated_at": "2024-03-21T13:24:28.096836Z"
    }
}

With the valid response received, you may want to pay attention to some important fields:

  • data.counterparty contains all information related to the individual who will receive any payments for that key:
    • data.counterparty.name represents their full name.
    • data.counterparty.tax_number represents the document/tax number (CPF/CNPJ in Brasil)
    • data.counterparty.bank_account represents the bank account that will receive the payment from that pix key.
  • data.id is the unique identifier for that key. We will use it to make the pay-out, if the counterparty found here is validated on your end. This will be the Pix Ref ID.
  • Some specific fields related to the QRCode response, different from the Pix Key:
    • data.description holds the description given in the creation of the QRCode.
    • data.expiration_date is the ISO8601 datetime representation of when the QRCode will expire and not accept a payment anymore.
    • data.key is the key that is represented by the QRCode.

If the key is not a valid existing one, you will receive a 4xx response akin to:

{
    "error": {
        "error_code": "DICT_BRCODE_NOT_FOUND",
        "error_message": "Brcode não foi encontrado. Referência: 00020101021126860014br.gov.bcb.pix0136018dd1d8-e1fb-a923-cfce-125c18201f830224018e13e0-7c31-9511-758d-52040000530398654040.015802BR5913Minha Empresa6008Curitiba61088025010462070503***6304FB79."
    }
}

Making a pay-out

When generating a new payout, there are some parameters that you will need to pay attention to (* for required fields):

  • Virtual Account ID*: the unique identifier for the virtual account that will send the money.
  • Pix Ref ID*: the unique identifier for a brcode you have checked prior. See above the id returned in the Check BRCode endpoint.
  • Pix Ref Type*: must be the type of the reference sent in the Pix Ref ID field. Possible values are "key", "brcode" or "bank_account". For a pix brcode, always select "brcode".
  • External ID: reference for your transaction in our system. It must be a unique string for every payout. Used to control the idempotence of a transaction.
  • Amount*: amount of the transaction, always represented in cents.
  • Description: the description of the transaction.

To generate the payout, send a POST request to our Pix Payout endpoint, using this payload:

POST: https://sandbox.trio.com.br/banking/cashout/pix

{
  "virtual_account_id": "c6377347-7891-46ac-ac2e-368d01ac0305",
  "pix_ref_id": "018e612f-3740-96ec-9ecf-de48c743a988",
  "pix_ref_type": "brcode",
  "amount": 1,
  "description": "Payment PIX - QRCode",
  "external_id": "950806b3-2f34-449d-86b6-437dafb625fc"
}

If everything is OK, you will receive a HTTP 201 response. It means that we have successfully scheduled the payout request, and the payload will be as follows:

{
  "data": {
    "payment_document_id": "018b480d-8da8-374a-6dd5-83b81788c605",
    "scheduled_at": "2023-10-19T12:59:34.947655Z"
  }
}

If it fails, you will receive a 400 response with the error message. You can check the complete error list here.

{
  "error": {
    "error_code": "PAYMENT_ACCOUNT_WITHOUT_BALANCE",
    "error_message": "Saldo insuficiente. Saldo atual R$ 3,13."
  }
}

Events

Created

Once we process the payout transaction, you will receive a webhook with the category payment_document and type created. This webhook contains all information regarding the transaction, and you can use the payment_document_id from the payout request to match it with the transaction:

{
    "category": "payment_document",
    "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
    "data": {
        "amount": {
            "amount": 1,
            "currency": "BRL"
        },
        "bank_account_id": "018e5bd1-067d-ee46-4825-402685959bc7",
        "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
        "counterparty": {
            "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
            "external_id": "018e5bd1-1fe9-ec37-8642-c2b2959ff317",
            "id": "018e5bd1-2007-c6b1-9591-8d554306c381",
            "inserted_at": "2024-03-20T12:23:35.692818Z",
            "ledger_type": "customer",
            "legal_name": null,
            "maximum_amount": null,
            "maximum_transactions": null,
            "name": "Farrell-McDermott LLC",
            "tax_number": "57088554850677",
            "updated_at": "2024-03-20T12:23:35.692818Z"
        },
        "counterparty_bank_account": {
            "account_digit": "7",
            "account_number": "73451",
            "account_type": "checking",
            "bank_ispb": "13203354",
            "bank_number": "425797",
            "branch": "1685",
            "id": "018e5cb5-40d5-a02f-c7fb-7ccda3bfe36f",
            "inserted_at": "2024-03-20T16:32:46.293427Z",
            "updated_at": "2024-03-20T16:32:46.293427Z"
        },
        "counterparty_bank_account_id": "018e5cb5-40d5-a02f-c7fb-7ccda3bfe36f",
        "counterparty_id": "018e5bd1-2007-c6b1-9591-8d554306c381",
        "description": "Saque de merchant.com",
        "end_to_end_id": null,
        "entity_id": "018e5bd0-91b9-c70c-1970-54a94d946326",
        "error_code": null,
        "error_message": null,
        "external_id": "107a1314-baf6-40c1-be67-2dcea53bb00c",
        "id": "018e614d-75fb-00c7-6e4e-987a8bb3fdfe",
        "origin_id": "018e5caf-98c8-016a-d411-82cfbd670714",
        "origin_type": "api_client",
        "payment_date": null,
        "pix_key": null,
        "receipt_url": null,
        "reconciliation_id": "018e614d-75fa-dfe2-002a-d750b1afc19d",
        "ref_id": "018e6146-c3d6-7726-6736-0651e5841f7d",
        "ref_type": "pix_brcode",
        "status": "created",
        "transaction_date": "2024-03-21T13:57:30.235010Z",
        "type": "pix",
        "virtual_account_id": "018e5bd1-12c2-f8d9-e8a5-078afb78344b",
        "without_fee_and_tax": false
    },
    "ref_id": "018e614d-75fb-00c7-6e4e-987a8bb3fdfe",
    "timestamp": "2024-03-21T13:57:30.430560Z",
    "type": "created"
}

At this moment, the transaction has not been completed yet, and can go through a success or a failure.

Success

When we complete the transaction successfully, you will receive a webhook notification with the category payment_document and type settled. You can use the payment_document_id to match with the ref_id from the payload:

{
  "category": "payment_document",
  "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
  "data": {
    "counterparty": {
      "company_id": "018e5bd0-9078-f906-69e6-b3145c5d3097",
      "external_id": "018e5bd1-1fe9-ec37-8642-c2b2959ff317",
      "id": "018e5bd1-2007-c6b1-9591-8d554306c381",
      "inserted_at": "2024-03-20T12:23:35.692818Z",
      "ledger_type": "customer",
      "legal_name": null,
      "maximum_amount": null,
      "maximum_transactions": null,
      "name": "Farrell-McDermott LLC",
      "tax_number": "57088554850677",
      "updated_at": "2024-03-20T12:23:35.692818Z"
    },
    "counterparty_bank_account": {
      "account_digit": "7",
      "account_number": "73451",
      "account_type": "checking",
      "bank_ispb": "36305779",
      "bank_number": "425797",
      "branch": "1685",
      "id": "018e5bd3-6f40-718b-d01c-9ee5d45032f7",
      "inserted_at": "2024-03-20T12:26:07.040509Z",
      "updated_at": "2024-03-20T12:26:07.040509Z"
    },
    "counterparty_bank_account_id": "018e5bd3-6f40-718b-d01c-9ee5d45032f7",
    "counterparty_id": "018e5bd1-2007-c6b1-9591-8d554306c381",
    "end_to_end_id": "018e6136-3668-06eb-d410-4745edfc9cca",
    "error_code": null,
    "error_message": null,
    "external_id": "950806b3-2f34-449d-86b6-437dafb625fc",
    "id": "018e6136-38b7-3f5c-0184-6b95ea63d590",
    "integration_status": "settled",
    "payment_document_id": "018e6136-30b7-f359-2702-f4502d7aa0c1",
    "receipt_url": "https://receipts.sandbox.trio.com.br/out/018e6136-38b7-3f5c-0184-6b95ea63d590",
    "timestamp": "2024-03-21T13:32:07.223058Z",
    "type": "settled"
  },
  "ref_id": "018e6136-30b7-f359-2702-f4502d7aa0c1",
  "timestamp": "2024-03-21T13:32:08.191001Z",
  "type": "settled"
}

At this moment, the transaction can be considered to be complete.

Failure

There are several reasons for a transaction to not be completed: insufficient balance, problems with the communication with the Central Bank of Brasil, and many others. When anything other than a success occurs, you will receive a webhook with the category payment_document and type reversed or failed: 

{
  "ref_id": "018b480d-8da8-374a-6dd5-83b81788c605",
  "category": "payment_document",
  "type": "reversed",
  "data": {
    "id": "018b479b-6ec2-9d45-05ab-278122742fbd",
    "type": "reversed",
    "timestamp": "2023-10-19T11:04:10.690756Z",
    "error_code": "TR0001",
    "external_id": "950806b3-2f34-449d-86b6-437dafb625fc",
    "receipt_url": "https://receipt.fitbank.com.br/receiptapi/pdf?filename=2023-10-19/mxzifvvg.pdf",
    "end_to_end_id": null,
    "error_message": "Saldo insuficiente para executar o pagamento",
    "counterparty_id": "0189a9e1-d0c8-200d-3cc8-6e70630ba9a3",
    "payment_document_id": "018b4797-ab1a-e96b-1a96-2d70c87d8456",
    "counterparty_bank_account_id": "0189a9e1-d0cb-faea-7467-aba34f9f1eff"
  },
  "timestamp": "2023-10-19T13:08:56.735025Z",
  "company_id": "a56c6e42-10c8-4876-946f-7d71595cecdc"
}

The failed webhook will fire when something was wrong before settling the document, such as the occurrence of a tax number being different from the Central Bank reference:

{
  "ref_id": "018b480d-8da8-374a-6dd5-83b81788c605",
  "category": "payment_document",
  "type": "failed",
  "data": {
    "id": "018b479b-6ec2-9d45-05ab-278122742fbd",
    "type": "failed",
    "timestamp": "2023-10-19T11:04:10.690756Z",
    "error_code": "TR0001",
    "external_id": "950806b3-2f34-449d-86b6-437dafb625fc",
    "receipt_url": null,
    "end_to_end_id": null,
    "error_message": "CPF/CNPJ informado é diferente do consultado na DICT.",
    "counterparty_id": "0189a9e1-d0c8-200d-3cc8-6e70630ba9a3",
    "payment_document_id": "018b4797-ab1a-e96b-1a96-2d70c87d8456",
    "counterparty_bank_account_id": "0189a9e1-d0cb-faea-7467-aba34f9f1eff"
  },
  "timestamp": "2023-10-19T13:08:56.735025Z",
  "company_id": "a56c6e42-10c8-4876-946f-7d71595cecdc"
}

If you desire to verify the payment document in our dashboard for a more complete view, you can do so by going to:

console.sandbox.trio.com.br/documents/out/{DOCUMENT_ID}

Updated 6 months ago