Consultar transação

GET/v1/transactions/{id}

Retorna o estado atual de uma cobrança ou saque.

Parâmetros

Parâmetro	Lugar	Descrição
`id`	path	`transactionId` retornado na criação.

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

Mesmos campos do endpoint de listar. pixPayload é null para saques. paidAt é null enquanto a transação não chegou em estado final.

Campos de PIX (opcionais)

Aparecem apenas em transações que foram efetivamente liquidadas na rede SPI:

Campo	Quando aparece	Descrição
`endToEndId`	Após `paid`, `refunded`, `partially_refunded` (PIX in ou saque pago)	E2E ID padrão BACEN do PIX original.
`payer`	Em `pix_in` que recebeu pagamento	Quem pagou — `{ name, document, documentType, bankAccount }`.
`beneficiary`	Em saques (`type: "withdrawal"`) que liquidaram	Quem recebeu — mesma estrutura de `payer`.
`refundEndToEndId`	Em saques devolvidos	E2E ID do PIX de devolução.

Em transações em pending, processing, failed, cancelled ou expired (não houve liquidação), esses campos são omitidos do JSON. Veja Eventos de webhook para detalhes do schema completo de payer e beneficiary.

Erros

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

Transações pertencentes a outro lojista também retornam 404 (não 403) — para não vazar existência.

Quando usar

Fallback do webhook: quando você suspeitar que perdeu um evento (sua aplicação caiu, timeout no recebimento).
Reconciliação: ao processar pedidos, sempre confirme o status final via consulta antes de liberar mercadoria/serviço.
Saques failed_unknown: aguarde 24h e consulte para ver se virou paid ou failed.

Exemplos

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 transações Consultar saldo