# Consultar Cash-Out por ID

Consulta los detalles y el estado de una transaccion PIX por el `transaction_id`.

## Endpoint

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

## Headers

| Header | Tipo | Obligatorio | Descripcion |
|--------|------|-------------|-------------|
| `Authorization` | String | Si | `ApiKey {client_id}:{client_secret}` |

## Path Parameters

| Parametro | Tipo | Obligatorio | Descripcion |
|-----------|------|-------------|-------------|
| `id` | String | Si | ID de la transaccion (`transaction_id`) |

## Ejemplo

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

La respuesta varia de acuerdo al estado de la transaccion. Este endpoint retorna el estado mas actualizado conocido por Monetarie para el identificador informado. Si el identificador no se encuentra, retorna `404`.

::: warning Transaccion rechazada NO aparece aqui por `transaction_id`
Algunos rechazos asincronicos pueden no localizarse por `transaction_id` inmediatamente. Use los endpoints alternativos:

- [GET /transactions/e2e/:e2e_id](/es/pix-cashout-e2e) para consultar por End-to-End ID
- [GET /transactions/ref/:external_id](/es/pix-query-external-id) para consultar por su identificador externo
- Webhook `pix.payout.rejected` / `pix.payout.failed` para notificacion en tiempo real con payload completo

Rechazos de validacion de entrada (400/422 inmediato) no pasan por este flujo porque ya retornaron error sincronico en el POST.
:::

---

### Respuesta -- Transaccion 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 | Descripcion |
|-------|------|-------------|
| `data.id` | String | ID interno de la transaccion en formato UUID canonico con guiones, cuando disponible |
| `data.transaction_id` | String | Identificador unico de la transaccion. Siempre lea el campo retornado; no derive reglas por prefijos |
| `data.end_to_end_id` | String | Identificador End-to-End en el SPI/BACEN |
| `data.external_id` | String | Identificador de su sistema. `null` si no informado |
| `data.type` | String | Tipo de la transaccion. Valores comunes: `pix`, `pix_return` |
| `data.direction` | String | Direccion del movimiento: `outbound` (cash-out), `inbound` (cash-in), `credit` o `debit` |
| `data.status` | String | Status normalizado (ver tabla abajo) |
| `data.amount` | Integer | Valor en **unidades base** (div 10.000 para reales). `300000` = R$ 30,00 |
| `data.fee_amount` | Integer | Tarifa cobrada en unidades base |
| `data.net_amount` | Integer | Valor neto en unidades base |
| `data.description` | String | Descripcion informada en la creacion |
| `data.counterparty_name` | String | Nombre de la contraparte (pagador o receptor) |
| `data.recipient_key` | String | Clave PIX del destinatario (solo para salidas) |
| `data.created_at` | String | Fecha de creacion (ISO 8601) |
| `data.completed_at` | String | Fecha de conclusion (ISO 8601), `null` si pendiente |

---

### Respuesta -- PIX OUT en Curso (200)

Retornado cuando la transaccion aun esta siendo procesada (antes de la confirmacion 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 | Descripcion |
|-----------------|------|-------------|
| `data.recipient` | Object | Datos del destinatario resueltos via DICT |
| `data.recipient.name` | String | Nombre del titular de la clave |
| `data.recipient.key` | String | Clave PIX utilizada |
| `data.recipient.key_type` | String | Tipo de la clave (`cpf`, `cnpj`, `email`, `phone`, `evp`) |
| `data.started_at` | String | Fecha de inicio del procesamiento (ISO 8601) |

---

### Respuesta -- Transaccion Rechazada (200)

Retornado por los endpoints [`/transactions/e2e/:e2e_id`](/es/pix-cashout-e2e) y `GET /transactions/ref/:external_id` cuando el PIX fue rechazado por el SPI o fallo durante el procesamiento.

```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 | Descripcion |
|-----------------|------|-------------|
| `data.failure_reason` | String | Motivo bruto del rechazo (formato: `"rejected: {CODE}"` para codigos BACEN, o descripciones de integracion como `"dict_key_not_found"`, `"ambiguous key"`, `"insufficient balance"`) |
| `data.reason_code` | String | Codigo estructurado extraido de `failure_reason`. Para rechazos BACEN, sigue ISO 20022 (`AC03`, `AB03`, `ED05`, `DUPL` etc). `null` cuando `failure_reason` no contiene codigo estructurado |
| `data.reason_description` | String | Descripcion humana del `reason_code`, **en ingles**. Ejemplos: `"Invalid creditor account number"` (AC03), `"Aborted by PSP of creditor"` (AB03), `"Settlement failed"` (ED05). `null` cuando el codigo no es reconocido |
| `data.recipient` | Object | Datos del destinatario (cuando disponibles). Puede ser omitido en fallas muy tempranas |
| `data.failed_at` | String | Fecha/hora del rechazo (ISO 8601) |

::: tip Estructura de los codigos de rechazo
Use `reason_code` y `reason_description` para enrutamiento programatico de errores. Mantenga `failure_reason` solo para logs y diagnostico. Vea la tabla completa de codigos en [PIX Cash-Out por Clave -- Codigos de Error](/es/pix-cashout-key#codigos-de-rechazo).
:::

---

### Respuesta -- QR Code No Pagado (200)

Retornado cuando el ID corresponde a un QR Code que aun no fue pagado.

```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 | Descripcion |
|-----------|-------------|
| `pending` | QR Code activo, aguardando pago |
| `settled` | QR Code pagado, pero la transaccion final aun esta en consolidacion. No trate como error; rehaga la consulta algunos segundos despues |
| `expired` | QR Code expirado |
| `cancelled` | QR Code cancelado manualmente |

**Nota**: cuando el QR esta pagado y la transaccion final ya fue consolidada, la respuesta pasa a ser la del shape "Transaccion Liquidada" arriba.

---

## Valores del campo `status`

::: tip Status del GET
El GET `/transactions/:id` retorna status normalizado para seguimiento operacional.

| Status | Significado |
|---|---|
| `processing` | PIX OUT aceptado y aun sin confirmacion final. Puede estar aguardando confirmacion del BACEN o reprocesamiento automatico por limite DICT |
| `settled` | BACEN confirmo liquidacion y el saldo ya fue movido. **Estado final de exito** |
| `pending` | Estado intermedio raro antes de la conclusion |
| `failed` | **Estado final de falla.** Rechazada por BACEN, expirada en reprocesamiento automatico (`DICT_QUEUE_TIMEOUT`) o falla operacional |

**Nota de compatibilidad**: rows legacy (anteriores a la consolidacion del vocabulario) pueden presentar `status: "completed"` o `status: "accepted"`. Tratelos como equivalentes a `"settled"`.

### Correspondencia con webhooks

- `pix.payout.queued` corresponde a `status: "processing"` mientras la transaccion aguarda reprocesamiento automatico
- `pix.payout.confirmed` siempre corresponde a `status: "settled"` en el GET
- `pix.payout.failed` y `pix.payout.rejected` siempre corresponden a `status: "failed"` en el GET

Para QR Codes (cash-in, fuera del alcance PIX OUT), los valores posibles son `pending`, `settled`, `expired` y `cancelled`, descritos en la seccion "QR Code No Pagado" arriba.
:::

## Respuesta de Error -- 404

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