# Query Cash-Out by ID

Queries the details and status of a PIX transaction by `transaction_id`.

## Endpoint

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

## Headers

| Header | Type | Required | Description |
|--------|------|----------|-------------|
| `Authorization` | String | Yes | `ApiKey {client_id}:{client_secret}` |

## Path Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | String | Yes | Transaction ID (`transaction_id`) |

## Example

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

The response varies with the transaction state. This endpoint returns the latest state known by Monetarie for the provided identifier. If the identifier is not found, it returns `404`.

::: warning Rejected transaction does NOT appear here by `transaction_id`
Some asynchronous rejections may not be located by `transaction_id` immediately. Use the alternative endpoints:

- [GET /transactions/e2e/:e2e_id](/en/pix-cashout-e2e) to query by End-to-End ID
- [GET /transactions/ref/:external_id](/en/pix-query-external-id) to query by your external identifier
- Webhook `pix.payout.rejected` / `pix.payout.failed` for real-time notification with full payload

Input validation rejections (immediate 400/422) do not go through this flow because the synchronous error was already returned on the POST.
:::

---

### Response -- Settled Transaction (200)

```json
{
  "worked": true,
  "data": {
    "id": "c7f3a8b1-2d4e-4f6a-9c1b-3e5f7a9b1d3e",
    "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"
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `data.id` | String | Internal transaction ID in canonical UUID format with hyphens, when available |
| `data.transaction_id` | String | Unique transaction identifier. Always read the returned field; do not derive rules from prefixes |
| `data.end_to_end_id` | String | End-to-End identifier in SPI/BACEN |
| `data.external_id` | String | Your system identifier. `null` if not provided |
| `data.type` | String | Transaction type. Common values: `pix`, `pix_return` |
| `data.direction` | String | Movement direction: `outbound` (cash-out), `inbound` (cash-in), `credit` or `debit` |
| `data.status` | String | Normalized status (see table below) |
| `data.amount` | Integer | Amount in **base units** (÷ 10,000 for BRL). `300000` = R$ 30.00 |
| `data.fee_amount` | Integer | Fee charged in base units |
| `data.net_amount` | Integer | Net amount in base units |
| `data.description` | String | Description provided at creation |
| `data.counterparty_name` | String | Counterparty name (payer or recipient) |
| `data.recipient_key` | String | Recipient PIX key (outbound only) |
| `data.created_at` | String | Creation date (ISO 8601) |
| `data.completed_at` | String | Completion date (ISO 8601), `null` if pending |

---

### Response -- PIX OUT in progress (200)

Returned when the transaction is still being processed (before BACEN confirmation).

```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"
    }
  }
}
```

| Additional field | Type | Description |
|------------------|------|-------------|
| `data.recipient` | Object | Recipient data resolved via DICT |
| `data.recipient.name` | String | Key holder's name |
| `data.recipient.key` | String | PIX key used |
| `data.recipient.key_type` | String | Key type (`cpf`, `cnpj`, `email`, `phone`, `evp`) |
| `data.started_at` | String | Processing start date (ISO 8601) |

---

### Response -- Rejected Transaction (200)

Returned by endpoints [`/transactions/e2e/:e2e_id`](/en/pix-cashout-e2e) and `GET /transactions/ref/:external_id` when the PIX was rejected by the SPI or failed during processing.

```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"
    }
  }
}
```

| Additional field | Type | Description |
|------------------|------|-------------|
| `data.failure_reason` | String | Raw rejection reason (format: `"rejected: {CODE}"` for BACEN codes, or integration descriptions like `"dict_key_not_found"`, `"ambiguous key"`, `"insufficient balance"`) |
| `data.reason_code` | String | Structured code extracted from `failure_reason`. For BACEN rejections, follows ISO 20022 (`AC03`, `AB03`, `ED05`, `DUPL`, etc.). `null` when `failure_reason` does not contain a structured code |
| `data.reason_description` | String | Human description of `reason_code`, **in English**. Examples: `"Invalid creditor account number"` (AC03), `"Aborted by PSP of creditor"` (AB03), `"Settlement failed"` (ED05). `null` when the code is not recognized |
| `data.recipient` | Object | Recipient data (when available). May be omitted in very early failures |
| `data.failed_at` | String | Rejection date/time (ISO 8601) |

::: tip Rejection code structure
Use `reason_code` and `reason_description` for programmatic error routing. Keep `failure_reason` only for logs and diagnostics. See the full code table in [PIX Cash-Out by Key -- Rejection codes](/en/pix-cashout-key#rejection-codes).
:::

---

### Response -- QR Code Not Paid (200)

Returned when the ID corresponds to a QR Code that has not yet been paid.

```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
  }
}
```

| QR status | Description |
|-----------|-------------|
| `pending` | QR Code active, awaiting payment |
| `settled` | QR Code paid, but the final transaction is still being consolidated. Do not treat it as an error; retry the query a few seconds later |
| `expired` | QR Code expired |
| `cancelled` | QR Code manually cancelled |

**Note**: when the QR is paid and the final transaction has already been consolidated, the response becomes the "Settled Transaction" shape above.

---

## `status` Field Values

::: tip GET status
GET `/transactions/:id` returns normalized status for operational tracking.

| Status | Meaning |
|---|---|
| `processing` | PIX OUT accepted and not final yet. It may be awaiting BACEN confirmation or automatic reprocessing due to a DICT limit |
| `settled` | BACEN confirmed settlement and the balance has already moved. **Final success state** |
| `pending` | Rare intermediate state before completion |
| `failed` | **Final failure state.** Rejected by BACEN, expired during automatic reprocessing (`DICT_QUEUE_TIMEOUT`) or operational failure |

**Compatibility note**: legacy rows (prior to vocabulary consolidation) may show `status: "completed"` or `status: "accepted"`. Treat them as equivalent to `"settled"`.

### Webhook correspondence

- `pix.payout.queued` corresponds to `status: "processing"` while the transaction awaits automatic reprocessing
- `pix.payout.confirmed` always corresponds to `status: "settled"` on GET
- `pix.payout.failed` and `pix.payout.rejected` always correspond to `status: "failed"` on GET

For QR Codes (cash-in, outside the PIX OUT scope), possible values are `pending`, `settled`, `expired` and `cancelled`, described in the "QR Code Not Paid" section above.
:::

## Error Response -- 404

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