Consultar uma transação

Recupera o objeto completo de uma transação a partir do seu ID (tra_*): status atual, valores, meio de pagamento, cliente, itens, recebíveis (receivables), splits, reembolsos, disputas e a linha do tempo de eventos. Use sempre que precisar do estado mais recente e detalhado de uma cobrança específica.

GET /v1/transactions/{transactionId}

Como funciona

A consulta é uma leitura síncrona e idempotente: ela apenas devolve o estado atual da transação no momento da chamada, sem alterar nada. O servidor identifica a transação pelo ID público (tra_...), valida o formato, verifica se ela pertence à sua conta e retorna o objeto inteiro com HTTP 200.

Diferente da listagem, que devolve uma projeção leve de cada transação (poucos campos por item, para varrer muitos registros de uma vez), a consulta por ID retorna o objeto completo — incluindo blocos pesados como customer, billing, items, receivables, timeline e os links HATEOAS em _links. Sempre que você tiver um ID e precisar de detalhe, prefira esta rota à listagem com filtro.

O campo status reflete o ponto do ciclo de vida em que a transação está. Os valores possíveis (enum) são:

Enum completo de status: pre-authorized, pending, failed, approved, refused, canceled, chargeback, unauthorized, refunded, fraud-review, analyzing, awaiting, dispute.

Quando usar (e quando não usar)

Use a consulta quando você já tem o ID e precisa do detalhe completo:

• Exibir o status e os dados de uma cobrança numa tela de pedido ou de suporte.
• Reconciliar um pagamento (conferir amount, receivables, paidAt).
• Confirmar o estado atual logo após receber um webhook (o webhook diz "algo mudou"; a consulta confirma o objeto inteiro).
• Recuperar links de pagamento (payment.pixQrCodeEmv, payment.billetUrl, payment.invoiceLink).

Prefira alternativas quando:

• Você não tem o ID, mas tem outro critério (e-mail do cliente, customId, período, status) — use a listagem com filtros.
• Você precisa varrer muitas transações — a listagem é paginada e mais barata.
• Você quer reagir a mudanças em vez de buscá-las — configure webhooks.

Requisição

Headers

Por ser uma leitura (GET, sem corpo), você não envia Content-Type nem X-Idempotency-Key. Nunca use Authorization: Bearer/Basic — a autenticação é sempre pelo header SelectKey.

Parâmetros de caminho

O ID é o valor que veio no campo id ao criar a transação ou ao listá-la. Veja as convenções de IDs.

Exemplo de requisição

curl https://api.selectwin.io/v1/transactions/tra_01hqzvabc \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Resposta

Sucesso retorna HTTP 200 OK com o objeto completo da transação. O exemplo abaixo é uma transação de cartão de crédito aprovada, com desconto aplicado e um recebível (receivable) já pago:

{
  "id": "tra_01hqzvabc",
  "customId": "PEDIDO-1042",
  "amount": 5000,
  "originalAmount": 5500,
  "status": "approved",
  "method": "credit",
  "currency": "BRL",
  "payment": {
    "provider": "selectwin",
    "version": "1.1",
    "refused": null,
    "reusable": false,
    "billetUrl": null,
    "billetBarcode": null,
    "billetSequence": null,
    "billetDocumentNumber": null,
    "billetReferenceNumber": null,
    "pixQrCodeEmv": null,
    "pixQrCodeUrl": null,
    "pixQrCodeImage": null,
    "acquirerTransactionNumber": "A1B2C3D4E5",
    "cardFirstDigits": "411111",
    "cardLastDigits": "1111",
    "cardBrand": "visa",
    "cardRegistered": false,
    "installments": 1,
    "expirationDate": null,
    "paidAt": "2026-04-12T17:56:33.000Z",
    "allowRenewPayment": false,
    "invoiceLink": "https://selectwin.io/invoices/tra_01hqzvabc"
  },
  "discount": {
    "value": 500,
    "type": "flat",
    "percentageOfAmount": null
  },
  "customer": {
    "id": "cus_01hqzvabc",
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "birthdate": "1990-01-15",
    "gender": "male",
    "document": { "type": "cpf", "number": "12345678901" },
    "telephone": {
      "countryCode": "55",
      "areaCode": "11",
      "number": "999999999",
      "line": "5511999999999"
    },
    "available": true,
    "delinquent": false,
    "externalReference": "CRM-USER-001",
    "additionalEmails": null,
    "metadata": {},
    "updatedAt": "2026-04-12T17:56:33.000Z",
    "createdAt": "2026-04-10T09:15:25.000Z"
  },
  "billing": {
    "address": {
      "id": "addr_01hqzvabc",
      "ownerId": "cus_01hqzvabc",
      "ownerType": "customer",
      "street": "Av. Paulista",
      "number": "1000",
      "complement": "Apt 42",
      "district": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "postcode": "01310-100",
      "country": "BR",
      "latitude": -23.5613,
      "longitude": -46.6558,
      "line": "Av. Paulista, 1000 - Apt 42 - Bela Vista, São Paulo - SP, 01310-100",
      "updatedAt": "2026-04-10T09:15:25.000Z",
      "createdAt": "2026-04-10T09:15:25.000Z"
    }
  },
  "shipping": null,
  "externalReference": "order-9981",
  "shippable": false,
  "spplited": true,
  "items": [
    {
      "id": "item_01hqzvabc",
      "name": "Premium Plan",
      "unitPrice": 5000,
      "quantity": 1,
      "currency": "BRL",
      "description": "Assinatura mensal",
      "images": ["https://cdn.example.com/product.png"],
      "isUpsell": false,
      "isOrderbump": false,
      "metadata": { "sku": "SKU-1" },
      "variantId": "var_01hqzvabc",
      "externalReference": "line-1",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:32.000Z"
    }
  ],
  "receivables": [
    {
      "id": "rec_01hqzvabc",
      "recipient": "bus_1234567890",
      "split": null,
      "status": "paid",
      "amount": 4805,
      "grossAmount": 5000,
      "anticipationFee": 0,
      "installmentNumber": 1,
      "description": null,
      "currency": "BRL",
      "authorizationCode": "654321",
      "paidAt": "2026-04-12T17:56:33.000Z",
      "refundedAt": null,
      "canceledAt": null,
      "expectedOn": "2026-05-12",
      "liable": true,
      "chargeProcessingFee": true,
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "splits": null,
  "refunds": null,
  "disputes": null,
  "timeline": [
    {
      "id": "tml_01hqzvabc",
      "message": "Transaction approved",
      "details": null,
      "type": "status",
      "updatedAt": "2026-04-12T17:56:33.000Z",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "callback": {
    "webhookUrl": "https://api.example.com/webhooks/transaction",
    "active": true
  },
  "metadata": {},
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:32.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/transactions/tra_01hqzvabc",
      "method": "GET",
      "description": "Read a transaction."
    }
  }
}

Campos principais

Objeto payment

Os dados do meio de pagamento ficam em campos planos dentro de payment (não há sub-objetos card/billet/pix). Os campos relevantes dependem do method; os demais vêm null.

Objeto discount

Demais blocos do objeto

Recebíveis (receivables) representam o dinheiro a receber, separado por parcela e por recipiente. amount é o valor líquido após taxas; grossAmount é o bruto. status: "paid" indica liquidado; expectedOn traz a data prevista de liquidação dos pendentes.

Navegando pelos _links (HATEOAS)

A resposta inclui _links com as ações disponíveis a partir do estado atual da transação (consultar, capturar, reembolsar, disputar, listar). Em vez de montar URLs à mão, siga o href correspondente. Os links presentes variam conforme o status — por exemplo, capture só aparece quando a transação está pre-authorized. Veja Recursos e HATEOAS.

Erros

Trate sempre pelo error.code (estável), nunca pela message. Veja o Catálogo de Códigos de Erro e o envelope de erro.

Distinga transactionIdIsInvalid (400, formato inválido — corrija o ID antes de repetir) de transactionNotFound (404, formato válido mas inexistente — não adianta repetir).

Boas práticas

• Não faça polling. Reaja a webhooks e use a consulta de forma pontual para confirmar o objeto após um evento. Veja Proibição de polling.
• Cacheie estados finais. Transações refunded, canceled, chargeback ou approved capturada não mudam mais — guarde o resultado e evite reconsultar. Estados como pending/analyzing ainda evoluem.
• Trate error.code, não message. Cubra transactionNotFound e transactionIdIsInvalid com fluxos distintos; para 429/5xx, repita com backoff respeitando error.retryAfterMinutes.
• Use receivables para reconciliar, não amount isolado: amount é o bruto cobrado; o que você recebe líquido (após taxas) está em receivables[].amount, com a data em expectedOn.
• Siga os _links em vez de construir URLs — eles refletem as ações válidas para o status atual e protegem sua integração contra mudanças de caminho.
• Guarde o ID, não o objeto inteiro. O objeto muda ao longo do ciclo de vida; persista o id (tra_...) e reconsulte quando precisar do estado atual.
• Exiba valores corretamente. Todos os valores monetários vêm em centavos (inteiros) e os timestamps em ISO 8601 UTC (...Z) — divida por 100 e converta o fuso apenas na exibição.

Veja também

• Visão geral de Transações — modelo do objeto e ciclo de vida.
• Criar transação — de onde vem o id que você consulta aqui.
• Listar transações — quando você não tem o ID e precisa filtrar.
• Capturar · Reembolsar · Disputar — ações de escrita sobre a transação.
• Convenções · Autenticação · Catálogo de Códigos de Erro
• Eventos de Webhook — a forma correta de saber quando uma transação muda.