Payout using a bank account (V1)

Generating a new Payout

To generate a new payout in V1 using a bank account, you must go through one step only. No checking of any reference is needed, since you have the whole bank account information.
A request can be made through the Generate pix payment endpoint

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

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 Bank Account*: an object containing such fields:
- Tax Number*: must be a document/tax number (CPF/CNPJ in Brasil).
- Name*: full name of the individual holding the bank account.
- Bank ISPB*: ISPB number representing the financial institution that holds the bank account. 8 digits mostly.
- Branch*: Bank account branch.
- Account Number*: Bank account number.
- Account Digit*: Bank account digit. Single digit.
- Account Type*: Bank account type. Possible values are: "checking", "savings", "payment", "salary".
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 bank account, always select "bank_account".
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

{
  "virtual_account_id": "c6377347-7891-46ac-ac2e-368d01ac0305",
  "pix_ref_bank_account": {
    "tax_number": "37926790869",
    "name": "John Doe",
    "bank_ispb": "18236120",
    "branch": "0001",
    "account_number": "336162",
    "account_digit": "7",
    "account_type": "payment"
  },
  "pix_ref_type": "bank_account",
  "amount": 1,
  "description": "Payment PIX - Bank Account",
  "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": "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": "bank_account",
    "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 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}