# Consultar Cash-Out por ID

Consulta os detalhes e o status de uma transação PIX pelo `transaction_id`.

## Endpoint

```
GET /api/external/transactions/:id
```

## Headers

| Header | Tipo | Obrigatório | Descrição |
|--------|------|-------------|-----------|
| `Authorization` | String | Sim | `ApiKey {client_id}:{client_secret}` |

## Path Parameters

| Parâmetro | Tipo | Obrigatório | Descrição |
|-----------|------|-------------|-----------|
| `id` | String | Sim | ID da transação (`transaction_id`) |

## Exemplo

```bash
curl -X GET https://api.monetarie.com/api/external/transactions/PIXOUT20260309a1b2c3d4e5f6 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

A resposta varia de acordo com o estado da transação. O endpoint retorna o estado mais atualizado conhecido pela Monetarie para o identificador informado. Se o identificador não for encontrado, retorna `404`.

::: warning Transação rejeitada NÃO aparece aqui por `transaction_id`
Algumas rejeições assíncronas podem não ser localizadas por `transaction_id` imediatamente. Use os endpoints alternativos:

- [GET /transactions/e2e/:e2e_id](/pix-cashout-e2e) para consultar pelo End-to-End ID
- [GET /transactions/ref/:external_id](/guide/concepts#external-id) para consultar pelo seu identificador externo
- Webhook `pix.payout.rejected` / `pix.payout.failed` para notificação em tempo real com payload completo

Rejeições de validação de entrada (400/422 imediato) não passam por este fluxo porque já retornaram erro síncrono no POST.
:::

---

### Resposta -- Transação Liquidada (200)

```json
{
  "worked": true,
  "data": {
    "id": "c7f3a8b12d4e4f6a9c1b3e5f7a9b1d3e",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E46026562202603091530abcdef01",
    "external_id": "order-9876",
    "type": "pix",
    "direction": "outbound",
    "status": "settled",
    "amount": 300000,
    "fee_amount": 350,
    "net_amount": 300350,
    "description": "Pagamento fornecedor",
    "counterparty_name": "Joao Silva",
    "recipient_key": "12345678901",
    "created_at": "2026-03-09T15:30:00Z",
    "completed_at": "2026-03-09T15:30:02Z"
  }
}
```

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `data.id` | String | ID interno da transação em formato UUID canônico com hifens, quando disponível |
| `data.transaction_id` | String | Identificador único da transação. Sempre leia o campo retornado; não derive regra a partir de prefixo |
| `data.end_to_end_id` | String | Identificador End-to-End no SPI/BACEN |
| `data.external_id` | String | Identificador do seu sistema. `null` se não informado |
| `data.type` | String | Tipo da transação. Valores comuns: `pix`, `pix_return` |
| `data.direction` | String | Direção do movimento: `outbound` (cash-out), `inbound` (cash-in), `credit` ou `debit` |
| `data.status` | String | Status normalizado (ver tabela abaixo) |
| `data.amount` | Integer | Valor em **unidades base** (div 10.000 para reais). `300000` = R$ 30,00 |
| `data.fee_amount` | Integer | Tarifa cobrada em unidades base |
| `data.net_amount` | Integer | Valor líquido em unidades base |
| `data.description` | String | Descrição informada na criação |
| `data.counterparty_name` | String | Nome da contraparte (pagador ou recebedor) |
| `data.recipient_key` | String | Chave PIX do destinatário (apenas para saídas) |
| `data.created_at` | String | Data de criação (ISO 8601) |
| `data.completed_at` | String | Data de conclusão (ISO 8601), `null` se pendente |

---

### Resposta -- PIX OUT em Andamento (200)

Retornado quando a transação ainda está sendo processada (antes da confirmação BACEN).

```json
{
  "worked": true,
  "data": {
    "status": "processing",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E46026562202603091530abcdef01",
    "amount": 300000,
    "fee_amount": 350,
    "net_amount": 300350,
    "external_id": "order-9876",
    "pix_key": "12345678901",
    "description": "Pagamento fornecedor",
    "type": "pix",
    "direction": "outbound",
    "payment_status": "processing",
    "started_at": "2026-03-09T15:30:00Z",
    "recipient": {
      "name": "Joao Silva",
      "key": "12345678901",
      "key_type": "cpf"
    }
  }
}
```

| Campo adicional | Tipo | Descrição |
|-----------------|------|-----------|
| `data.recipient` | Object | Dados do destinatário resolvidos via DICT |
| `data.recipient.name` | String | Nome do titular da chave |
| `data.recipient.key` | String | Chave PIX utilizada |
| `data.recipient.key_type` | String | Tipo da chave (`cpf`, `cnpj`, `email`, `phone`, `evp`) |
| `data.started_at` | String | Data de início do processamento (ISO 8601) |

---

### Resposta -- Transação Rejeitada (200)

Retornado pelos endpoints [`/transactions/e2e/:e2e_id`](/pix-cashout-e2e) e `GET /transactions/ref/:external_id` quando o PIX foi rejeitado pelo SPI ou falhou durante o processamento.

```json
{
  "worked": true,
  "data": {
    "status": "failed",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E46026562202603091530abcdef01",
    "amount": 300000,
    "fee_amount": 350,
    "external_id": "order-9876",
    "type": "pix",
    "direction": "outbound",
    "payment_status": "failed",
    "failure_reason": "rejected: AB03",
    "reason_code": "AB03",
    "reason_description": "Aborted by PSP of creditor",
    "started_at": "2026-03-09T15:30:00Z",
    "failed_at": "2026-03-09T15:30:05Z",
    "recipient": {
      "name": "Joao Silva",
      "key": "12345678901"
    }
  }
}
```

| Campo adicional | Tipo | Descrição |
|-----------------|------|-----------|
| `data.failure_reason` | String | Motivo bruto da rejeição (formato: `"rejected: {CODE}"` para códigos BACEN, ou descrições de integração como `"dict_key_not_found"`, `"ambiguous key"`, `"insufficient balance"`) |
| `data.reason_code` | String | Código estruturado extraído de `failure_reason`. Para rejeições BACEN, segue ISO 20022 (`AC03`, `AB03`, `ED05`, `DUPL` etc). `null` quando `failure_reason` não contém código estruturado |
| `data.reason_description` | String | Descrição humana do `reason_code`, **em inglês**. Exemplos: `"Invalid creditor account number"` (AC03), `"Aborted by PSP of creditor"` (AB03), `"Settlement failed"` (ED05). `null` quando o código não é reconhecido |
| `data.recipient` | Object | Dados do destinatário (quando disponíveis). Pode ser omitido em falhas muito precoces |
| `data.failed_at` | String | Data/hora da rejeição (ISO 8601) |

::: tip Estrutura dos códigos de rejeição
Use `reason_code` e `reason_description` para roteamento programático de erros. Mantenha `failure_reason` apenas para logs e diagnóstico. Veja a tabela completa de códigos em [PIX Cash-Out por Chave -- Códigos de Erro](/pix-cashout-key#codigos-de-rejeicao).
:::

---

### Resposta -- QR Code Não Pago (200)

Retornado quando o ID corresponde a um QR Code que ainda não foi pago.

```json
{
  "worked": true,
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "transaction_id": "7popu57v6us7p6pcicgq12345",
    "end_to_end_id": null,
    "external_id": "order-9876",
    "type": "pix_qrcode",
    "status": "pending",
    "amount": 300000,
    "fee_amount": 0,
    "net_amount": 300000,
    "description": "Cobrança PIX",
    "direction": "credit",
    "counterparty_name": null,
    "recipient_key": "12345678901",
    "created_at": "2026-03-09T15:30:00Z",
    "completed_at": null
  }
}
```

| Status QR | Descrição |
|-----------|-----------|
| `pending` | QR Code ativo, aguardando pagamento |
| `settled` | QR Code pago, mas a transação final ainda está em consolidação. Não trate como erro; refaça a consulta alguns segundos depois |
| `expired` | QR Code expirado |
| `cancelled` | QR Code cancelado manualmente |

**Nota**: quando o QR está pago e a transação final já foi consolidada, a resposta passa a ser a do shape "Transação Liquidada" acima.

---

## Valores do campo `status`

::: tip Status do GET
O GET `/transactions/:id` retorna status normalizado para acompanhamento operacional.

| Status | Significado |
|---|---|
| `processing` | PIX OUT aceito e ainda sem confirmação final. Pode estar aguardando confirmação do BACEN ou reprocessamento automático por limite DICT |
| `settled` | BACEN confirmou liquidação e o saldo já foi movimentado. **Estado final de sucesso** |
| `pending` | Estado intermediário raro antes da conclusão |
| `failed` | **Estado final de falha.** Rejeitada pelo BACEN, expirada em reprocessamento automático (`DICT_QUEUE_TIMEOUT`) ou falha operacional |

**Nota de compatibilidade**: rows legadas (anteriores à consolidação do vocabulário) podem apresentar `status: "completed"` ou `status: "accepted"`. Trate-os como equivalentes a `"settled"`.

### Correspondência com webhooks

- `pix.payout.queued` corresponde a `status: "processing"` enquanto a transação aguarda reprocessamento automático
- `pix.payout.confirmed` sempre corresponde a `status: "settled"` no GET
- `pix.payout.failed` e `pix.payout.rejected` sempre correspondem a `status: "failed"` no GET

Para QR Codes (cash-in, fora do escopo PIX OUT), os valores possíveis são `pending`, `settled`, `expired` e `cancelled`, descritos na seção "QR Code Não Pago" acima.
:::

## Resposta de Erro -- 404

```json
{
  "worked": false,
  "detail": "Transação não encontrada"
}
```