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

curl -X GET https://api.minhakonta.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 Minha Konta for the provided identifier. If the identifier is not found, it returns 404.

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 to query by End-to-End ID
• GET /transactions/ref/: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)

{
  "worked": true,
  "data": {
    "id": "c7f3a8b1-2d4e-4f6a-9c1b-3e5f7a9b1d3e",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E04838403202603091530abcdef01",
    "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).

{
  "worked": true,
  "data": {
    "status": "processing",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E04838403202603091530abcdef01",
    "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 and GET /transactions/ref/:external_id when the PIX was rejected by the SPI or failed during processing.

{
  "worked": true,
  "data": {
    "status": "failed",
    "transaction_id": "PIXOUT20260309a1b2c3d4e5f6",
    "end_to_end_id": "E04838403202603091530abcdef01",
    "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)

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.

---

Response -- QR Code Not Paid (200)

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

{
  "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

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

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