Referência da API

Buscar transação

Busca uma transação por ID interno, seu externalId ou pelo identificador endToEnd do PIX. O parâmetro searchBy define qual campo é usado.

GET/transactions/:transactionId

Autenticação

HTTP Basic Auth. Envie sua secret key no header:

Authorization: Basic {base64(secret:SUA_SECRET_KEY)}

Parâmetros

transactionIdstring (path)obrigatório

O valor a buscar. Pode ser o ID numérico interno, seu externalId ou o identificador endToEnd do PIX — escolha o searchBy correspondente.

Exemplo: 1234567

searchBy'id' | 'externalId' | 'end2End'opcional

Qual campo usar na busca. Padrão id.

Exemplo: externalId

Respostas

200

Transação encontrada. Traz os dados do pagador (payer*) e do recebedor (receiver*). Os campos de recebedor vêm preenchidos quando a rede informa a conta que recebeu (PIX); podem vir null em métodos que não expõem esse dado.

JSON

{
  "id": "17913320791467683016950003",
  "currency": "BRL",
  "method": "PIX",
  "brand": null,
  "installments": null,
  "externalId": "pedido-5678",
  "status": "APPROVED",
  "amount": 1000,
  "postbackUrl": "https://seu-dominio.com/webhook",
  "pixCode": "00020126580014br.gov.bcb.pix...",
  "paymentInstruction": null,
  "type": "TRANSACTION",
  "expiresAt": "2026-04-08T15:32:01.923Z",

  "payerDocument": "12345678901",
  "payerEmail": "joao@email.com",
  "payerFullName": "João da Silva",
  "payerPhone": "+5511998888777",
  "payerInstitution": "NU PAGAMENTOS",
  "payerIspb": "19318318",

  "receiverName": "Nome da sua empresa",
  "receiverDocument": "12345678000190",
  "receiverInstitution": "iHubGames",
  "receiverIspb": "18236120",

  "amountSeller": 900,
  "description": "Pedido #5678",
  "createdAt": "2026-04-08T14:32:01.923Z",
  "approvedAt": "2026-04-08T14:32:45.102Z",
  "end2End": "E12345678202604081432123456789012",
  "costFee": 100
}

404

Nenhuma transação encontrada para o identificador e searchBy informados.

JSON

{
  "statusCode": 404,
  "message": "Transaction not found"
}

Exemplos

cURL

# Por ID interno (padrão)
curl -X GET "https://api.ihubplay.com/transactions/1234567" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

# Pelo seu externalId
curl -X GET "https://api.ihubplay.com/transactions/pedido-5678?searchBy=externalId" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

# Pelo endToEnd do PIX (útil para conciliar com extrato bancário)
curl -X GET "https://api.ihubplay.com/transactions/E12345678202604081432123456789012?searchBy=end2End" \
  -H "Authorization: Basic $(echo -n 'secret:SUA_SECRET_KEY' | base64)"

JavaScript

const token = Buffer.from("secret:" + process.env.IHUBGAMES_SECRET_KEY).toString("base64");

const res = await fetch("https://api.ihubplay.com/transactions/pedido-5678?searchBy=externalId", {
  headers: { Authorization: `Basic ${token}` },
});

if (res.status === 404) {
  console.log("não encontrada");
} else {
  const tx = await res.json();
  console.log(tx.status, tx.amount / 100);
}