Consultar Cash-In por ID

Consulta o status e detalhes de uma transação PIX pelo ID da transação.

Endpoint

GET /api/external/transactions/:id

Headers

Header	Tipo	Obrigatório	Descrição
Authorization	String	Sim	ApiKey {client_id}:{client_secret}
X-Key-Case	String	Não	Defina como camelCase para receber os campos da resposta em camelCase (padrão é snake_case)

Path Parameters

Parâmetro	Tipo	Obrigatório	Descrição
id	String	Sim	ID da transação (transaction_id)

Exemplo

curl -X GET https://api.owem.com.br/api/external/transactions/7popu57v6us7p6pcicgq12345 \
  -H "Authorization: ApiKey $CLIENT_ID:$CLIENT_SECRET"

Resposta de Sucesso (200)

{
  "worked": true,
  "data": {
    "id": "a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d",
    "transaction_id": "7popu57v6us7p6pcicgq12345",
    "end_to_end_id": "E37839059202603071530000001",
    "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": "37839059000188",
    "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	Descrição
worked	Boolean	true indica sucesso na operação
data.id	String	ID interno da transação. Para transações liquidadas (shape padrão acima), o formato é hex lowercase de 32 caracteres sem hifens (ex: a1b2c3d4e5f64a7b8c9d0e1f2a3b4c5d). Em outros shapes (QR ainda não linkado, falhas), o campo pode não estar presente ou pode ter outro formato (UUID com hifens quando derivado diretamente do qrcodes.id)
data.transaction_id	String	Identificador público da transação. Para PIX IN via este pipeline, assume o formato PIXIN + E2E (ex: PIXINE37839059202603071530000001) -- o prefixo é sempre PIXIN seguido do próprio E2E (que começa com E). Use como identificador opaco; não tente extrair o E2E via string-split sem cuidado, pois a concatenação não tem separador
data.end_to_end_id	String	ID ponta-a-ponta do BACEN (E2E, formato ^E\d{8}[a-zA-Z0-9]{22,26}$)
data.external_id	String | null	Identificador do seu sistema. null se não informado na criação
data.type	String	pix para transações liquidadas via pipeline normal. pix_qrcode quando o id consultado resolve apenas em qrcodes (QR ainda pending/expired/cancelled, OU QR já pago mas ainda não vinculado à linha final em transactions -- janela curta pós-settlement). pix_return em devoluções recebidas (ver Devoluções PIX)
data.status	String	Status atual (veja tabela abaixo)
data.amount	Integer	Valor em unidades base (÷ 10.000 para reais). 300000 = R$ 30,00
data.fee_amount	Integer	Valor da tarifa em unidades base
data.net_amount	Integer	Valor líquido em unidades base (para PIX IN, normalmente amount - fee_amount)
data.description	String | null	Descrição da transação
data.direction	String	inbound para recebimentos, outbound para envios
data.counterparty_name	String | null	Para inbound, nome do pagador; para outbound, nome do recebedor
data.payer_document	String | null	CPF/CNPJ do pagador. Presente em recebimentos quando o banco emissor enviar
data.recipient_document	String | null	CPF/CNPJ do recebedor
data.recipient_key	String | null	Chave PIX usada no recebimento (evp/email/phone/cpf/cnpj)
data.payer_ispb	String | null	ISPB de 8 dígitos do banco pagador
data.payer_bank_name	String | null	Nome do banco pagador (resolvido a partir do ISPB)
data.created_at	String	Data de criação (ISO 8601 em UTC)
data.completed_at	String | null	Data de conclusão (ISO 8601 em UTC), null se ainda pendente

Endpoint também responde a envios

Apesar do foco deste documento em recebimentos, GET /api/external/transactions/:id é o mesmo endpoint para PIX IN e PIX OUT. Quando o id resolver para um envio em processamento ou uma falha, a resposta tem o formato descrito em Consultar Cash-Out por ID (status: processing / status: failed com reason_code/reason_description).

Status Possíveis

Valores possíveis retornados no campo status:

Status	Origem	Descrição
settled	transactions	Estado final de sucesso. Pagamento recebido e creditado na conta. Mesmo valor do webhook pix.charge.paid com status: "paid".
settled	qrcodes (fallback)	Emitido também quando o QR tem paid_at mas a linha final em transactions ainda não foi persistida -- janela curta entre Phase 2 ACCC do BACEN e a persistência local. Nesse caso type: "pix_qrcode" e alguns campos (end_to_end_id, counterparty_name, payer_*) podem vir populados apenas parcialmente
pending	qrcodes	QR Code gerado, aguardando pagamento
expired	qrcodes	QR Code expirado (TTL configurável por conta, padrão 1h). Também aplicado automaticamente em QRs cuja expires_at já passou mas ainda não foram processados pelo worker
cancelled	qrcodes	QR Code cancelado manualmente pelo merchant (via portal) ou em operações administrativas (ex: migração em massa estático→dinâmico de abril/2026)
failed	failed_transactions	Tentativa de crédito rejeitada (ex: limite excedido, conta bloqueada, duplicidade, rejeição BACEN). O campo reason_code indica o motivo estruturado.

Quando failed é emitido

Embora menos frequente do que em cash-out, recebimentos podem falhar em cenários específicos: rejeição do BACEN pós-ACSP (ex: AC03, AM02, DUPL), limite operacional excedido, conta destinatária bloqueada ou inexistente. Nesses casos, o registro aparece em failed_transactions com direction = "inbound" e o endpoint retorna o seguinte formato adicional (campos exclusivos do caminho failed):

{
  "worked": true,
  "data": {
    "status": "failed",
    "transaction_id": "PIXINE37839059202603071530000001",
    "end_to_end_id": "E37839059202603071530000001",
    "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"
    }
  }
}

Quando você consulta pelo tx_id do QR e o QR ainda não foi pago, o endpoint retorna pending/expired/cancelled (derivado de qrcodes, sem linha em transactions). Nesse caso o payload é reduzido: id, transaction_id (= tx_id), amount, status, description, recipient_key (chave PIX do QR), type: "pix_qrcode", direction: "credit", created_at (quando o QR foi gerado) e completed_at (quando pago, ou null). O campo counterparty_name é null neste shape (só é preenchido quando há linha real em transactions).

Nota sobre cancelamento em massa: durante a migração de QRs estáticos para dinâmicos em abril/2026, um lote de QRs estáticos com valor fixo ativos foi cancelado administrativamente (status cancelled). Consultas retornam esse status normalmente; não é necessário tratamento especial.

Resposta de Erro (404)

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

Resposta de Erro (401)

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

Polling vs Webhook

Para acompanhar o status de uma cobrança, prefira utilizar Webhooks em vez de polling. Caso precise consultar, use intervalos de no mínimo 5 segundos.