# Consultar Cash-In por ID

Consulta el status y detalles de una transaccion PIX por el ID de la transaccion.

## Endpoint

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

## Headers

| Header | Tipo | Obligatorio | Descripcion |
|--------|------|-------------|-------------|
| `Authorization` | String | Si | `ApiKey {client_id}:{client_secret}` |
| `X-Key-Case` | String | No | Defina como `camelCase` para recibir los campos de la respuesta en camelCase (default es snake_case) |

## 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/7popu57v6us7p6pcicgq12345 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"
```

## Respuesta de Exito (200)

```json
{
  "worked": true,
  "data": {
    "id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
    "transaction_id": "7popu57v6us7p6pcicgq12345",
    "end_to_end_id": "E46026562202603071530000001",
    "external_id": "order-9876",
    "type": "pix",
    "status": "settled",
    "amount": 300000,
    "fee_amount": 0,
    "net_amount": 300000,
    "description": "Pedido #1234",
    "direction": "inbound",
    "counterparty_name": "Maria Santos",
    "payer_document": "12345678901",
    "recipient_document": "46026562000165",
    "recipient_key": "contato@empresa.com.br",
    "payer_ispb": "60701190",
    "payer_bank_name": "ITAU UNIBANCO S.A.",
    "created_at": "2026-03-07T15:30:00Z",
    "completed_at": "2026-03-07T15:30:02Z"
  }
}
```

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| `worked` | Boolean | `true` indica exito en la operacion |
| `data.id` | String | ID interno de la transaccion. Para transacciones **liquidadas** (shape default arriba), el formato es **hex lowercase de 32 caracteres sin guiones** (ej: `a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d`). En otros shapes (QR aun no linkeado, fallas), el campo puede no estar presente o puede tener otro formato (UUID con guiones cuando derivado directamente del `qrcodes.id`) |
| `data.transaction_id` | String | Identificador publico de la transaccion. Para PIX IN via este pipeline, asume el formato `PIXIN` + E2E (ej: `PIXINE46026562202603071530000001`) -- **el prefijo es siempre `PIXIN` seguido del propio E2E** (que comienza con `E`). Use como identificador opaco; **no** intente extraer el E2E via string-split sin cuidado, pues la concatenacion no tiene separador |
| `data.end_to_end_id` | String | ID punta-a-punta del BACEN (E2E, formato `^E\d{8}[a-zA-Z0-9]{22,26}$`) |
| `data.external_id` | String \| null | Identificador de su sistema. `null` si no informado en la creacion |
| `data.type` | String | `pix` para transacciones liquidadas via pipeline normal. `pix_qrcode` cuando el `id` consultado resuelve solo en `qrcodes` (QR aun `pending`/`expired`/`cancelled`, O QR ya pagado pero aun no vinculado a la linea final en `transactions` -- ventana corta pos-settlement). `pix_return` en devoluciones recibidas (ver [Devoluciones PIX](/es/pix-refund)) |
| `data.status` | String | Status actual (vea tabla abajo) |
| `data.amount` | Integer | Valor en **unidades base** (÷ 10.000 para reales). `300000` = R$ 30,00 |
| `data.fee_amount` | Integer | Valor de la tarifa en unidades base |
| `data.net_amount` | Integer | Valor neto en unidades base (para PIX IN, normalmente `amount - fee_amount`) |
| `data.description` | String \| null | Descripcion de la transaccion |
| `data.direction` | String | `inbound` para recibimientos, `outbound` para envios |
| `data.counterparty_name` | String \| null | Para `inbound`, nombre del **pagador**; para `outbound`, nombre del **receptor** |
| `data.payer_document` | String \| null | CPF/CNPJ del pagador. Presente en recibimientos cuando el banco emisor envie |
| `data.recipient_document` | String \| null | CPF/CNPJ del receptor |
| `data.recipient_key` | String \| null | Clave PIX usada en el recibimiento (evp/email/phone/cpf/cnpj) |
| `data.payer_ispb` | String \| null | ISPB de 8 digitos del banco pagador |
| `data.payer_bank_name` | String \| null | Nombre del banco pagador (resuelto a partir del ISPB) |
| `data.created_at` | String | Fecha de creacion (ISO 8601 en UTC) |
| `data.completed_at` | String \| null | Fecha de conclusion (ISO 8601 en UTC), `null` si aun pendiente |

::: info Endpoint tambien responde a envios
A pesar del foco de este documento en recibimientos, `GET /api/external/transactions/:id` es **el mismo endpoint para PIX IN y PIX OUT**. Cuando el `id` resuelva para un envio en procesamiento o una falla, la respuesta tiene el formato descrito en [Consultar Cash-Out por ID](/es/pix-cashout-status) (`status: processing` / `status: failed` con `reason_code`/`reason_description`).
:::

## Status Posibles

Valores posibles retornados en el campo `status`:

| Status | Origen | Descripcion |
|--------|--------|-------------|
| `settled` | `transactions` | **Estado final de exito.** Pago recibido y acreditado en la cuenta. Mismo valor del webhook `pix.charge.paid` con `status: "paid"`. |
| `settled` | `qrcodes` (fallback) | Emitido tambien cuando el QR tiene `paid_at` pero la linea final en `transactions` aun no fue persistida -- ventana corta entre Phase 2 ACCC del BACEN y la persistencia local. En ese caso `type: "pix_qrcode"` y algunos campos (`end_to_end_id`, `counterparty_name`, `payer_*`) pueden venir llenados solo parcialmente |
| `pending` | `qrcodes` | QR Code generado, aguardando pago |
| `expired` | `qrcodes` | QR Code expirado (TTL configurable por cuenta, default 1h). Tambien aplicado automaticamente en QRs cuya `expires_at` ya paso pero aun no fueron procesados por el worker |
| `cancelled` | `qrcodes` | QR Code cancelado manualmente por el merchant (via portal) o en operaciones administrativas (ej: migracion en masa estatico→dinamico de abril/2026) |
| `failed` | `failed_transactions` | Tentativa de credito **rechazada** (ej: limite excedido, cuenta bloqueada, duplicidad, rechazo BACEN). El campo `reason_code` indica el motivo estructurado. |

::: info Controles opt-in de recepcion - ningun impacto por default
Si la cuenta receptora activo un control **opt-in** de recepcion ("verificacion de pagador esperado" o "bloquear recepcion de CNPJ"), un PIX recibido que no cumpla el criterio es **rechazado y devuelto al pagador** (devolucion BACEN) en vez de acreditado - visible por el status de la transaccion y por los webhooks. Estos controles vienen **desactivados por default**; sin activacion, todas las recepciones son procesadas normalmente. Vea [Controles de Cuenta](/es/account-controls).
:::

::: info Cuando `failed` es emitido
Aunque menos frecuente que en cash-out, recibimientos **pueden** fallar en escenarios especificos: rechazo del BACEN pos-ACSP (ej: `AC03`, `AM02`, `DUPL`), limite operacional excedido, cuenta destinataria bloqueada o inexistente. En esos casos, el registro aparece en `failed_transactions` con `direction = "inbound"` y el endpoint retorna el siguiente formato adicional (campos exclusivos del camino `failed`):

```json
{
  "worked": true,
  "data": {
    "status": "failed",
    "transaction_id": "PIXINE46026562202603071530000001",
    "end_to_end_id": "E46026562202603071530000001",
    "amount": 300000,
    "fee_amount": 0,
    "external_id": "order-9876",
    "type": "pix",
    "direction": "inbound",
    "payment_status": "failed",
    "failure_reason": "rejected: AC03",
    "reason_code": "AC03",
    "reason_description": "Invalid creditor account number",
    "started_at": "2026-03-07T15:30:00Z",
    "failed_at": "2026-03-07T15:30:02Z",
    "recipient": {
      "name": "Empresa Exemplo LTDA",
      "key": "contato@empresa.com.br"
    }
  }
}
```

Cuando usted consulta por el `tx_id` del QR y el QR aun no fue pagado, el endpoint retorna `pending`/`expired`/`cancelled` (derivado de `qrcodes`, sin linea en `transactions`). En ese caso el payload es reducido: `id`, `transaction_id` (= `tx_id`), `amount`, `status`, `description`, `recipient_key` (clave PIX del QR), `type: "pix_qrcode"`, `direction: "credit"`, `created_at` (cuando el QR fue generado) y `completed_at` (cuando pagado, o `null`). El campo `counterparty_name` es `null` en este shape (solo es llenado cuando hay linea real en `transactions`).

**Nota sobre cancelacion en masa**: durante la migracion de QRs estaticos a dinamicos en abril/2026, un lote de QRs estaticos con valor fijo activos fue cancelado administrativamente (status `cancelled`). Consultas retornan ese status normalmente; no es necesario tratamiento especial.
:::

## Respuesta de Error (404)

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

## Respuesta de Error (401)

```json
{
  "error": {
    "status": 401,
    "message": "Missing API key credentials. Use Authorization: ApiKey <client_id>:<client_secret>"
  }
}
```

::: tip Polling vs Webhook
Para acompanar el status de un cobro, prefiera utilizar [Webhooks](/es/webhooks) en vez de polling. En caso de necesitar consultar, use intervalos de al menos 5 segundos.
:::