Consultar transacción

GET/v1/transactions/{id}

Devuelve el estado actual de un cobro o retiro.

Parámetros

Parámetro	Ubicación	Descripción
`id`	path	`transactionId` devuelto en la creación.

Respuesta `200 OK`

{
  "transactionId": "Q4t9aV...",
  "type": "pix_in",
  "amountCents": 1000,
  "feeCents": 10,
  "netCents": 990,
  "status": "paid",
  "externalRef": "pedido-123",
  "pixPayload": "00020126580014BR.GOV.BCB.PIX...",
  "expiresAt": 1715000000,
  "paidAt": 1714999100000,
  "createdAt": 1714998000000,
  "updatedAt": 1714999100000,
  "endToEndId": "E18236120202605080330abc123",
  "payer": {
    "name": "Maria Santos",
    "document": "98765432100",
    "documentType": "cpf",
    "bankAccount": {
      "ispb": "18236120",
      "branch": "1",
      "account": "914453272"
    }
  }
}

Mismos campos que el endpoint de listar. pixPayload es null para retiros. paidAt es null mientras la transacción no haya llegado a un estado final.

Campos PIX (opcionales)

Aparecen solo en transacciones efectivamente liquidadas en la red SPI:

Campo	Cuándo aparece	Descripción
`endToEndId`	Tras `paid`, `refunded`, `partially_refunded` (PIX in o retiro pagado)	E2E ID estándar BACEN del PIX original.
`payer`	En `pix_in` que recibió pago	Quién pagó — `{ name, document, documentType, bankAccount }`.
`beneficiary`	En retiros (`type: "withdrawal"`) liquidados	Quién recibió — misma estructura de `payer`.
`refundEndToEndId`	En retiros devueltos	E2E ID del PIX de devolución.

En transacciones en pending, processing, failed, cancelled o expired (sin liquidación), estos campos se omiten del JSON. Ver Eventos de webhook para el esquema completo de payer y beneficiary.

Errores

HTTP	`error`
400	`"transactionId inválido."`
401	`"API key inválida ou revogada."`
404	`"Transação não encontrada."`

Las transacciones que pertenecen a otro comerciante también devuelven 404 (no 403) — para no filtrar la existencia.

Cuándo usar

Fallback del webhook: cuando sospeches que perdiste un evento (tu aplicación cayó, timeout en la recepción).
Conciliación: al procesar pedidos, confirma siempre el estado final por consulta antes de liberar mercadería/servicio.
Retiros failed_unknown: espera 24 h y consulta para ver si pasó a paid o failed.

Ejemplos

curl https://api.internationalfinance.com.br/v1/transactions/Q4t9aV... \
  -H "Authorization: Bearer $INFI_API_KEY"

const res = await fetch(
  `https://api.internationalfinance.com.br/v1/transactions/${id}`,
  { headers: { Authorization: `Bearer ${process.env.INFI_API_KEY}` } },
)
if (res.status === 404) return null
const tx = await res.json()

import os, requests
 
res = requests.get(
    f"https://api.internationalfinance.com.br/v1/transactions/{id}",
    headers={"Authorization": f"Bearer {os.environ['INFI_API_KEY']}"},
)
if res.status_code == 404:
    tx = None
else:
    tx = res.json()

<?php
$client = new GuzzleHttp\Client(['http_errors' => false]);
$res = $client->get("https://api.internationalfinance.com.br/v1/transactions/{$id}", [
  'headers' => ['Authorization' => 'Bearer ' . getenv('INFI_API_KEY')],
]);
$tx = $res->getStatusCode() === 404 ? null : json_decode($res->getBody(), true);

Listar transacciones Consultar saldo