Using Pix Key

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?)]*$``	[e-mail]
Phone number	^\+[1-9][0-9]\d{1,14}$	[phone]
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.: [e-mail]

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

Document Lifecycle

Each document that is processed by Trio generates and sequence of stages that represent the evolution of the transaction in our system:

• Created - we receive the transaction and enqueue for processing

• Registering - we start to process the settlement

• Settled - transaction was successfully processed and settled, the balance is deducted in your account, this is a final stage

• Failed - transaction was sent and not processed due to invalid information or declined by the bank, this is a final stage

Follow a diagram that represents the flow:

Webhook events

To avoid overcommunication, we only send asynchronous communication using webhooks for the final stages.

Created

This event will be triggered when we receive the payout transaction, and we successfully registered in our system to process the transaction. We'll create a payment document that represents the payout transaction and notify you through webhooks with the category payment_document and type created.

Webhook example

Settled

This event will be triggered when successfully complete the payout transaction. We'll update the payment document and notify you through webhooks with the category payment_document and type settled.

Webhook example

Failed

This event will be triggered when a transaction was not processed, rejected or declined. We'll update the payment document and notify you through webhooks with the category payment_document and type failed.

Webhook example