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

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

Respuesta de Exito (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	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: PIXINE37839059202603071530000001) -- 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)
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

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 (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.

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):

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

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)

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

Respuesta de Error (401)

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

Polling vs Webhook

Para acompanar el status de un cobro, prefiera utilizar Webhooks en vez de polling. En caso de necesitar consultar, use intervalos de al menos 5 segundos.