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:

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

processing → settled

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:

Do not immediately create another withdrawal request.

The transaction may still have been processed successfully. Before retrying:

Query using the same external_id;
Validate webhook notifications;
Validate reconciliation status;
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).

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

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:

QR Code Request → Payment Confirmation → Final Financial Transaction

Cash In `settled` Webhook Example

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

created → settled

created → failed → settled

created → failed → failed → settled

Important Lifecycle Behavior

For Cash In operations, failed is not necessarily a final status. A failed event only means:

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:

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.

Practical Guide

Operations

Best practices for integration

Understanding Cash In and Cash Out IDs

Identifier Overview

Cash Out

How Cash Out Identifiers Work

Recommended Usage

Cash Out Lifecycle

Understanding `failed`

Understanding `settled`

Response Time Expectations

Timeout Handling

Cash In

How Cash In Identifiers Work

Important

Settlement Flow

Cash In `settled` Webhook Example

Cash In Lifecycle

Important Lifecycle Behavior

Common `failed` Scenarios

Understanding `settled`

Response Time Expectations

Retry Recommendation

`external_id` and Idempotency

Idempotency Window

Best Practices

Webhook Processing Recommendations

Final Summary

​Understanding Cash In and Cash Out IDs

​Identifier Overview

​Cash Out

​How Cash Out Identifiers Work

​Recommended Usage

​Cash Out Lifecycle

​Understanding failed

​Understanding settled

​Response Time Expectations

​Timeout Handling

​Cash In

​How Cash In Identifiers Work

​Important

​Settlement Flow

​Cash In settled Webhook Example

​Cash In Lifecycle

​Important Lifecycle Behavior

​Common failed Scenarios

​Understanding settled

​Response Time Expectations

​Retry Recommendation

​external_id and Idempotency

​Idempotency Window

​Best Practices

​Webhook Processing Recommendations

​Final Summary

Understanding Cash In and Cash Out IDs

Identifier Overview

Cash Out

How Cash Out Identifiers Work

Recommended Usage

Cash Out Lifecycle

Understanding `failed`

Understanding `settled`

Response Time Expectations

Timeout Handling

Cash In

How Cash In Identifiers Work

Important

Settlement Flow

Cash In `settled` Webhook Example

Cash In Lifecycle

Important Lifecycle Behavior

Common `failed` Scenarios

Understanding `settled`

Response Time Expectations

Retry Recommendation

`external_id` and Idempotency

Idempotency Window

Best Practices

Webhook Processing Recommendations

Final Summary