# 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:

<table><thead><tr><th width="169.21484375">Type</th><th>Regex</th><th>Example</th></tr></thead><tbody><tr><td>Email</td><td>`^[a-z0-9.!#$&#x26;'*+\/=?^_{}~-]+@[a-z0-9?(?:.a-z0-9?)]*$``</td><td><a href="mailto:johndoe@example.com">johndoe@example.com</a></td></tr><tr><td>Phone number</td><td>^\+[1-9][0-9]\d{1,14}$</td><td>+5510998765432</td></tr><tr><td>CPF (tax number)</td><td>^[0-9]{11}$</td><td>12345678901</td></tr><tr><td>CNPJ (tax number)</td><td>^[0-9]{14}$</td><td>12345678901234</td></tr><tr><td>Random</td><td>[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}</td><td>123e4567-e89b-12d3-a456-426655440000</td></tr></tbody></table>

### 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.: <johndoe@example.com>
* **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://api.sandbox.trio.com.br/banking/cashout/pix/v2`

```json
{
  "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:

```json
{
  "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](https://developers.trio.com.br/reference/errors).

```json
{
  "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:

<figure><img src="https://1207169478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FOqaIqStBTblubAbDZACC%2Fuploads%2F1Tli3J5ITG2bLcPvVNif%2F14e749fbfc43b263e4feaf5fe32ad587b93045278f92c9641850068ce32d8642-Screenshot_2024-12-05_at_09.50.14.png?alt=media&#x26;token=06632682-67b7-4a2c-834f-7c254cecbc6c" alt=""><figcaption></figcaption></figure>

### 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](https://docs.trio.com.br/developers/webooks/events/payment-document#payment_document.created)

#### 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 <kbd>payment\_document</kbd> and type `settled`.

[Webhook example](https://docs.trio.com.br/developers/webooks/events/payment-document#payment_document.settled)

#### 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](https://docs.trio.com.br/developers/webooks/events/payment-document#payment_document.failed)