Payout using a pix key (V2)

Considering the fact that a Pix key represents a bank account in the Pix arrangement, this is the most straight forward way to complete a payout using Pix.

The only information you need from the customer is their Pix key. Currently, we support 5 types of keys and we use RegEx to validate the format:

Type	Regex	Example
Email	`^[a-z0-9.!#$&'+\/=?^_{}~-]+@[a-z0-9?(?:.a-z0-9?)]$``	[email protected]
Phone number	^\+[1-9][0-9]\d{1,14}$	+5510998765432
CPF (tax number)	^[0-9]{11}$	12345678901
CNPJ (tax number)	^[0-9]{14}$	12345678901234
Random	[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}	123e4567-e89b-12d3-a456-426655440000

Generating a new Payout

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

Virtual Account ID*: the unique identifier for the virtual account that will send the money.
Type*: the type of the value you are sending as a reference. Possible values: "key", "brcode" or "manual".
Reference*: the value of the reference you desire to pay to. For Pix Keys, this should be the value of the pix key. e.g.: [email protected]
Reference Tax Number: the document/tax number of the individual you desire to pay to. This is an optional field.
- If you don't send the reference tax number, we will make a pay-out to the individual that holds the reference (the pix key).
- If you do send the reference tax number, we will verify whether the tax number of the reference (the pix key) is the same as the tax number you sent. If it is equal, we allow the payment; if not, we reject it.
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 this single 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/v2

{
  "virtual_account_id": "c6377347-7891-46ac-ac2e-368d01ac0305",
  "type": "key",
  "reference": "60772568030",
  "reference_tax_number": "39801903969",
  "external_id": "950806b3-2f34-449d-86b6-437dafb625fc",
  "amount": 1,
  "description": "Payout using Pix key"
}

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": "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",
    "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": "950806b3-2f34-449d-86b6-437dafb625fc",
    "id": "018e6136-30b7-f359-2702-f4502d7aa0c1",
    "origin_id": "018e5caf-98c8-016a-d411-82cfbd670714",
    "origin_type": "api_client",
    "payment_date": null,
    "pix_key": null,
    "receipt_url": null,
    "reconciliation_id": "018e6136-30b7-afa2-c96f-e0020142d952",
    "ref_id": "018e612f-3740-96ec-9ecf-de48c743a988",
    "ref_type": "pix_key",
    "status": "created",
    "transaction_date": "2024-03-21T13:32:05.175244Z",
    "type": "pix",
    "virtual_account_id": "018e5bd1-12c2-f8d9-e8a5-078afb78344b",
    "without_fee_and_tax": false
  },
  "ref_id": "018e6136-30b7-f359-2702-f4502d7aa0c1",
  "timestamp": "2024-03-21T13:32:06.175964Z",
  "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 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": "018b4797-aad5-d8cf-4fee-1e61ced82a40",
    "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": "018b4797-aad5-d8cf-4fee-1e61ced82a40",
    "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}