> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trio.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Best practices for integration

# Understanding Cash In and Cash Out IDs

During the integration process with the **Trio API**, it is important to understand how identifiers behave differently between **Cash In** and **Cash Out** operations.

These identifiers are essential for:

* Financial reconciliation;
* Transaction tracking;
* Idempotency validation;
* Duplicate prevention;
* Transaction lookup;
* Operational investigations.

***

# Identifier Overview

| Transaction Type | Identifier Returned on Creation | Final Financial Identifier Availability |
| ---------------- | ------------------------------- | --------------------------------------- |
| Cash Out         | `data.out_document_id`          | Immediately                             |
| Cash In          | `data.id` (`ref_id`)            | After `settled` webhook                 |

***

# Cash Out

## How Cash Out Identifiers Work

For Cash Out operations, the financial transaction is created immediately during the request.

Because of this, the API instantly returns the final transaction identifier:

```json theme={null}
{
  "data": {
    "out_document_id": "0192057d-ab3f-3651-f054-6ef9c8e68f20"
  }
}
```

The returned `out_document_id` already represents the finalized financial document.

***

## Recommended Usage

The identifier should be persisted and used for:

* Transaction status queries;
* Financial reconciliation;
* Receipt validation;
* Operational support investigations;
* Audit trails.

***

## Cash Out Lifecycle

```text theme={null}
processing → settled
```

or

```text theme={null}
processing → failed
```

Both `settled` and `failed` are final states.

Once either status is reached:

* No further events will occur;
* The transaction lifecycle is permanently closed.

***

## Understanding `failed`

If a Cash Out reaches `failed`:

* The withdrawal was not completed;
* The transaction is finalized immediately;
* No additional updates will occur.

Possible causes include:

* Invalid Pix key;
* Banking rejection;
* Insufficient balance;
* Banking processing failures.

***

## Understanding `settled`

When a Cash Out reaches `settled`:

* The transfer was completed successfully;
* Funds were delivered;
* The transaction becomes immutable.

***

## Response Time Expectations

| Scenario                   | Expected Time   |
| -------------------------- | --------------- |
| Stable environment average | `200ms ~ 280ms` |
| Temporary oscillation      | Up to `1000ms`  |

***

## Timeout Handling

If a Cash Out request times out:

```text theme={null}
Do not immediately create another withdrawal request.
```

The transaction may still have been processed successfully.

Before retrying:

1. Query using the same `external_id`;
2. Validate webhook notifications;
3. Validate reconciliation status;
4. Contact Trio support if necessary.

Creating another request without validation may generate duplicate payouts.

***

# Cash In

## How Cash In Identifiers Work

For Cash In operations, the initial request creates only the QR Code request.

At this stage:

* The payment has not yet happened;
* No financial settlement exists yet;
* No final transaction document exists.

The API returns only the QR Code identifier (`ref_id`).

```json theme={null}
{
  "data": {
    "id": "0192bebb-fbdb-b6f3-6be1-7153e373b609",
    "status": "created",
    "description": "Paid to merchant.com",
    "hash": "00020101021226790014br.gov.bcb.pix2557brcode-h.trio.com.br/...",
    "amount": {
      "currency": "BRL",
      "amount": 100
    },
    "external_id": "49d754c2-ac14-4219-bbe4-3e78e9ab8067",
    "virtual_account_id": "019296ff-1f72-2ad7-0201-41de08355fda",
    "origin_type": "api_client",
    "pix_key_id": "019296ff-1f94-ecec-2220-96bfd06e8e59"
  }
}
```

***

## Important

The returned `data.id` should be interpreted as:

```text theme={null}
QR Code Identifier (ref_id)
```

and not as the final financial transaction identifier.

The final `document_id` is generated only after successful settlement.

***

## Settlement Flow

Once the payment is completed successfully, Trio sends a `settled` webhook containing:

* `external_id`;
* `ref_id`;
* Final transaction `id`.

This structure allows the association between:

```text theme={null}
QR Code Request → Payment Confirmation → Final Financial Transaction
```

***

## Cash In `settled` Webhook Example

```json theme={null}
{
  "data": {
    "amount": {
      "amount": 100,
      "currency": "BRL"
    },
    "external_id": "49d754c2-ac14-4219-bbe4-3e78e9ab8067",
    "id": "0194bd99-65cd-5ee9-70f6-44d61ae5aa41",
    "receipt_url": "https://receipts.sandbox.trio.com.br/.../in/0194bd99-65cd-5ee9-70f6-44d61ae5aa41",
    "ref_id": "0192bebb-fbdb-b6f3-6be1-7153e373b609",
    "type": "pix",
    "virtual_account_id": "0194412c-c559-5452-942e-7f4b4975c666"
  },
  "type": "settled",
  "category": "collecting_document",
  "timestamp": "2025-01-31T18:22:14.477163Z"
}
```

***

## Cash In Lifecycle

Possible lifecycle sequences:

```text theme={null}
created → settled
```

```text theme={null}
created → failed → settled
```

```text theme={null}
created → failed → failed → settled
```

***

## Important Lifecycle Behavior

For Cash In operations, `failed` is not necessarily a final status.

A `failed` event only means:

```text theme={null}
A payment attempt was rejected
```

It does not mean:

* The QR Code expired;
* The QR Code was canceled;
* The operation is permanently closed.

The QR Code remains active and may still receive future payment attempts.

***

## Common `failed` Scenarios

Examples include:

* Third-party payment attempts;
* Rejected payer validations;
* Business rule validation failures.

***

## Understanding `settled`

Once a Cash In reaches `settled`:

* The payment is finalized;
* The final `document_id` is generated;
* The QR Code is automatically closed;
* No further events will occur.

After settlement, additional `failed` events are not possible.

***

## Response Time Expectations

| Scenario                      | Expected Time  |
| ----------------------------- | -------------- |
| Stable environment average    | `80ms ~ 100ms` |
| Recommended timeout threshold | Up to `500ms`  |

***

## Retry Recommendation

If no response is received within `500ms` during QR Code generation:

* A new request may be created;
* A new `external_id` must be used.

***

# `external_id` and Idempotency

The `external_id` field is the primary reconciliation identifier between your platform and Trio.

This field must be unique for every operation.

***

## Idempotency Window

Cash In and Cash Out operations enforce an idempotency window of:

```text theme={null}
24 hours (1 day)
```

During this period:

* The same `external_id` cannot be reused;
* Duplicate requests may return the previous transaction;
* This prevents accidental duplicate operations.

***

## Best Practices

Recommended:

* Use UUIDs;
* Persist all identifiers in your database;
* Associate identifiers with internal orders/payments;
* Query transactions before retrying requests.

Avoid:

* Reusing identifiers;
* Sequential IDs;
* Blind automatic retries;
* Creating new operations without previous validation.

***

# Webhook Processing Recommendations

For production environments:

* Process webhooks asynchronously;
* Return `HTTP 200 OK` immediately;
* Persist webhook payloads;
* Maintain audit history;
* Avoid long-running synchronous processing.

Webhooks should always be treated as the source of truth for final transaction status updates.

***

# Final Summary

Cash In and Cash Out operations behave differently and should be handled differently during integration.

For Cash Out:

* The final transaction identifier is returned immediately;
* `failed` and `settled` are terminal states;
* Timeout retries must be handled carefully to avoid duplicate payouts.

For Cash In:

* The initial request creates only the QR Code reference (`ref_id`);
* The final financial transaction exists only after settlement;
* `failed` does not necessarily represent a permanent failure;
* Multiple payment attempts may occur before settlement;
* The final `document_id` is received only through webhook notification.

For both operation types:

* `external_id` should always be unique;
* All identifiers should be persisted for reconciliation;
* Webhooks should be considered the authoritative source of transaction state;
* Proper timeout and retry handling is critical to prevent duplicate operations and reconciliation inconsistencies.