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.minhakonta.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 Minha Konta para o identificador informado. Se o identificador não for encontrado, retorna 404.

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 para consultar pelo End-to-End ID
GET /transactions/ref/: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": "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"
  }
}

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

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

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)

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.

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`

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

Consultar Cash-Out por ID ​

Endpoint ​

Headers ​

Path Parameters ​

Exemplo ​

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

Resposta -- PIX OUT em Andamento (200) ​

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

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

Valores do campo status ​

Correspondência com webhooks ​

Resposta de Erro -- 404 ​

Consultar Cash-Out por ID

Endpoint

Headers

Path Parameters

Exemplo

Resposta -- Transação Liquidada (200)

Resposta -- PIX OUT em Andamento (200)

Resposta -- Transação Rejeitada (200)

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

Valores do campo `status`

Correspondência com webhooks

Resposta de Erro -- 404