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

# Modelo de identidade

> id, externalId, transactionId e endToEndId — quem define, persistência e uso em refund e suporte.

## Campos centrais

| Campo           | Quem define       | Uso                                                                                                                         |
| --------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `id`            | Plataforma (UUID) | Chave primária em consultas e em `POST /api/pix/refund-in/{id}` — **é o UUID do cash-in**, não o identificador do parceiro. |
| `externalId`    | Integrador        | Idempotência e correlação com ERP/pedido. Deve ser **único** por operação quando a API assim exigir.                        |
| `transactionId` | Parceiro (BaaS)   | ID da transação no BaaS; informativo e usado em webhooks.                                                                   |
| `endToEndId`    | Pix (BACEN)       | Identificador fim a fim após liquidação.                                                                                    |

## Regras de refund (crítico)

Para **devolver um recebimento**, o path é:

`POST /api/pix/refund-in/{id}`

onde `{id}` é o **`id` (UUID) do cash-in** retornado em `POST /api/pix/cash-in`, **não** o `transactionId` do parceiro.

Para **consultar um refund-in** após a criação, use o UUID do **refund** em `GET /api/pix/refund/{id}` (ver documentação de detalhe).

## O que persistir (recomendação operacional)

1. Sempre o **`id`** (UUID) retornado no `201` de cada recurso.
2. O **`externalId`** que você enviou (cópia de negócio).
3. `transactionId` e `endToEndId` quando retornados ou presentes no webhook, para rastreio e conciliação com o parceiro.
4. Em devoluções parciais, o **`id` do refund-in** (via `201` de `refund-in` ou `GET` de lista) para auditoria e deduplicação de eventos de estorno.

## Implicações

| Tema                     | Detalhe                                                                                                                                                              |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Rastreabilidade**      | Suporte e análise de incidente pedem, em geral, `id` da plataforma e, quando existir, `endToEndId`.                                                                  |
| **Webhook de estorno**   | Em `pix_cash_in_reversal`, a semântica de `event.id` e `event.external_id` difere de `pix_cash_in` (ver [referência de eventos](/webhooks/webhook-event-reference)). |
| **Reversão de cash-out** | O webhook `pix_cash_out_reversal` carrega o UUID do **cash-out** em `event.id` (não do refund-in, pois o fluxo é outro).                                             |

## Referência

* [Ciclo de vida](/core-concepts/transaction-lifecycle)
* [Assumir PENDING/PAID corretamente](/core-concepts/status-model)