Payout using pix key

Since 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. At the moment we support 5 types of keys and we use regex to validate the format:

Type	Regex	Example
Email	^[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 generate a new payout, there are some important parameters that you need to pay attention:

Virtual Account ID: virtual account that will send the money.
External ID: reference of your transaction in our system. It's unique for every payout. Used to control the idempotence of a transaction.
Amount: amount of the transaction, always represented in cents.
Type: could be key, brcode or manual.
Reference: the reference of the type in our example, will be the key that we want to complete the payout.

To generate the payout, send a POST request to 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 a201 response. It means that we successfully schedule the payout request, the payload will be like this:

{
  "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."
  }
}

Once we process the payout transaction you'll receive a webhook with 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 the transaction:

{
  "ref_id": "018b480d-8da8-374a-6dd5-83b81788c605",
  "category": "payment_document",
  "type": "created",
  "data": {
    "amount": {
      "amount": 1,
      "currency": "BRL"
    },
    "bank_account_id": "703a3e51-cc75-4669-9d85-15dea257d33a",
    "company_id": "a56c6e42-10c8-4876-946f-7d71595cecdc",
    "counterparty_bank_account_id": "cd70b12b-c7c7-4e5d-9a1a-41b3fa87b68c",
    "counterparty_id": "e1c26958-f13f-4c09-a8a0-a181c505ecc4",
    "description": "Payout using Pix key",
    "end_to_end_id": null,
    "entity_id": "3c2e9aab-6923-49bd-a0b9-9f0b77b2abe0",
    "error_code": null,
    "error_message": null,
    "external_id": "950806b3-2f34-449d-86b6-437dafb625fc",
    "id": "018b480d-8da8-374a-6dd5-83b81788c605",
    "payment_date": null,
    "pix_key": "60772568030",
    "receipt_url": null,
    "reconciliation_id": "01HD40V3D8B8VPGK5AWW4Y5YH6",
    "ref_id": "cd70b12b-c7c7-4e5d-9a1a-41b3fa87b68c",
    "ref_type": "bank_account",
    "status": "created",
    "transaction_date": "2023-10-19T13:08:49.704284Z",
    "type": "pix",
    "virtual_account_id": "c6377347-7891-46ac-ac2e-368d01ac0305",
    "without_fee_and_tax": false
  },
  "timestamp": "2023-10-19T13:08:50.220850Z",
  "company_id": "a56c6e42-10c8-4876-946f-7d71595cecdc"
}

At this moment the transaction is not completed yet and can go trough a success or failure path.

Success

When we complete the transaction successfully you'll 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:

{
  "ref_id": "018b480d-8da8-374a-6dd5-83b81788c605",
  "category": "payment_document",
  "type": "settled",
  "data": {
    "counterparty_bank_account_id": "cd70b12b-c7c7-4e5d-9a1a-41b3fa87b68c",
    "counterparty_id": "e1c26958-f13f-4c09-a8a0-a181c505ecc4",
    "end_to_end_id": "E1320335420231019130853965518183",
    "error_code": null,
    "error_message": null,
    "external_id": "950806b3-2f34-449d-86b6-437dafb625fc",
    "id": "018b480d-a8d4-a158-2ff9-cc083652ed26",
    "integration_status": "Paid",
    "payment_document_id": "018b480d-8da8-374a-6dd5-83b81788c605",
    "receipt_url": "https://receipt.fitbank.com.br/receiptapi/pdf?filename=2023-10-19/xeoultzj.pdf",
    "timestamp": "2023-10-19T13:08:56.660379Z",
    "type": "settled"
  },
  "timestamp": "2023-10-19T13:08:56.735025Z",
  "company_id": "a56c6e42-10c8-4876-946f-7d71595cecdc"
}

At this moment the transaction you can consider the transaction was completed.

Failure

There are several reasons to not complete a transaction, insufficient balance, problems in the communication with the Central Bank and many others. When this occurs you will receive a webhook with category payment_document and type reversed or failure:

{
  "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",
    "integration_status": "Cancel",
    "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"
}