Visão geral

Uma transação representa uma cobrança na Selectwin: o registro do pagamento de um cliente por cartão, Pix, boleto ou Nupay, com seu valor, status, recebíveis e histórico. Este é o recurso central da API — quase todo fluxo de receita começa criando uma transação e acompanhando seu ciclo de vida até a liquidação, reembolso ou disputa. Esta página explica o modelo do objeto, os estados pelos quais ele passa e todas as operações disponíveis.

Toda chamada usa a base https://api.selectwin.io/v1 e o header de autenticação SelectKey (nunca Authorization: Bearer/Basic). Valores monetários são inteiros em centavos (9900 = R$ 99,00) e datas seguem ISO 8601 em UTC (2026-04-12T17:56:33.000Z). Veja Convenções e Autenticação.

O que é uma transação

Uma transação é a unidade de cobrança da plataforma. Ela amarra, em um único objeto:

• O pagamento — meio (credit, debit, billet, pix, nupay), valor, parcelas, e os dados específicos do provedor (QR Code Pix, linha digitável do boleto, dígitos do cartão).
• O cliente (customer) — embutido ou referenciado por cus_*.
• Os itens (items) — as linhas do carrinho que somam o amount.
• Os recebíveis (receivables) — quanto e quando você recebe (já descontadas taxas e antecipação), inclusive em parcelas e splits.
• O histórico (timeline) e os eventos de reembolso (refunds) e disputa (disputes).

Cada transação tem um identificador opaco com prefixo tra_ (ex.: tra_01hqzvabc). Não faça parsing do ID — trate-o como string opaca. Você também pode definir um customId/externalReference para reconciliar com o seu sistema.

Modelo do objeto

O exemplo abaixo é uma versão anotada e resumida de uma transação aprovada por cartão de crédito. A resposta completa (com merchant, _links, billing, receivables completos e timeline) aparece em Create e Read.

{
  "id": "tra_01hqzvabc",            // ID opaco da transação (prefixo tra_)
  "customId": "PEDIDO-1042",         // seu identificador legível, opcional
  "amount": 5000,                    // valor atual em centavos (após captura parcial/desconto)
  "originalAmount": 5500,            // valor original antes de descontos/ajustes
  "status": "approved",              // estado atual (ver tabela de status)
  "method": "credit",                // meio de pagamento
  "currency": "BRL",                 // ISO 4217 — hoje apenas BRL
  "payment": {
    "provider": "selectwin",
    "version": "1.1",
    "refused": null,                 // motivo da recusa quando status = refused; null se ok
    "cardFirstDigits": "411111",
    "cardLastDigits": "1111",
    "cardBrand": "visa",
    "cardRegistered": false,
    "installments": 1,               // número de parcelas (crédito)
    "paidAt": "2026-04-12T17:56:33.000Z",
    "invoiceLink": "https://selectwin.io/invoices/tra_01hqzvabc"
    // Pix/boleto preenchem aqui: pixQrCodeEmv, pixQrCodeUrl, billetUrl, billetBarcode...
  },
  "customer": {
    "id": "cus_01hqzvabc",
    "firstName": "João",
    "lastName": "Silva",
    "email": "[email protected]",
    "document": { "type": "cpf", "number": "12345678901" }
  },
  "items": [
    {
      "id": "item_01hqzvabc",
      "name": "Premium Plan",
      "unitPrice": 5000,             // preço unitário em centavos
      "quantity": 1,
      "currency": "BRL"
    }
  ],
  "discount": null,                  // { value, type, percentageOfAmount } quando há desconto
  "externalReference": "order-9981",
  "shippable": false,
  "spplited": false,                 // true quando há splits (grafia do campo é "spplited")
  "receivables": [ /* parcelas a receber, com fees e expectedOn */ ],
  "splits": null,                    // regras de repasse a terceiros
  "refunds": null,                   // reembolsos registrados
  "disputes": null,                  // disputas/chargebacks
  "timeline": [
    {
      "id": "tml_01hqzvabc",
      "message": "Transaction created",
      "type": "status",
      "createdAt": "2026-04-12T17:56:33.000Z"
    }
  ],
  "metadata": {},                    // pares chave/valor seus (máx. 40 chaves)
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:32.000Z"
}

Campos principais

Status e ciclo de vida

O campo status reflete o estado da transação. Os valores possíveis (enum do contrato) são:

O diagrama abaixo mostra as transições típicas. Os caminhos dependem do meio e do parâmetro capture:

Ciclo de vida dos recebíveis

Cada transação aprovada gera um ou mais recebíveis (receivables) — o dinheiro que efetivamente cairá no seu saldo, já líquido de taxas (fees) e antecipação (anticipationFee), com data prevista em expectedOn. Em parcelamento, há um recebível por parcela (installmentNumber). Os recebíveis têm seu próprio status (scheduled, pending, paid, refunded, dispute, chargeback, canceled) e disparam eventos receivable.*.

Operações

Chamada mínima de exemplo

Criar uma cobrança Pix de R$ 50,00:

curl -X POST https://api.selectwin.io/v1/transactions \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "payment": { "currency": "BRL", "method": "pix", "pix": { "expiresInMinutes": 30 } },
    "geolocation": { "ipAddress": "189.44.12.1" },
    "customer": { "id": "cus_01hqzvabc" }
  }'

A resposta 201 traz o pixQrCodeEmv/pixQrCodeUrl em payment e status: "pending". Os detalhes de cada campo do corpo estão em Create.

Captura: automática vs. manual

Para cartão de crédito, o parâmetro payment.capture decide o fluxo:

• capture: true — autoriza e captura na mesma chamada. A transação vai direto para approved. É o padrão de e-commerce comum.
• capture: false — apenas autoriza (reserva o valor). A transação fica pre-authorized e você precisa chamar Capture depois para cobrar de fato. Útil para reservas de hotel, aluguel de veículos ou pedidos cujo valor final só se confirma na expedição. Pré-autorizações têm prazo de validade no emissor; se você não capturar a tempo, elas são liberadas (canceled).

A captura pode ser parcial: informe um amount menor que o autorizado em POST .../capture. O saldo não capturado é liberado.

Conceitos e relações

• Customers — uma transação sempre tem um cliente. Reutilize um existente com customer.id (cus_*) ou envie os dados completos para criação implícita.
• Cards — para cobrar um cartão salvo, use payment.card.id em vez de enviar os dados completos (PAN/CVV). Veja Segurança e PCI.
• Items, descontos e splits — os items definem o amount (ou envie amount direto, sem itens); discount ajusta o total (flat em centavos ou percentage); splits repartem o repasse entre recebedores (type: percentage ou flat).
• Webhooks — a forma correta de acompanhar mudanças de estado de forma assíncrona. Eventos de transação incluem transaction.pending, transaction.approved, transaction.refused, transaction.failed, transaction.canceled, transaction.refunded, transaction.chargeback, transaction.dispute, transaction.fraud-review, transaction.pre-authorized, transaction.unauthorized e transaction.awaiting. Os recebíveis disparam receivable.created, receivable.scheduled, receivable.paid, receivable.refunded, receivable.dispute, receivable.canceled e receivable.deleted. Veja Webhook Events.

Erros

Trate erros pelo error.code (estável), nunca pela message. Códigos específicos de transações e os transversais mais comuns:

A lista completa por recurso está em Códigos de Erro; a estrutura do envelope de erro, em Tratamento de Erros.

Boas práticas

1. Acompanhe por webhooks, não por polling. Pix e boleto são assíncronos; configure callback.webhookUrl e reaja aos eventos transaction.*/receivable.*. Veja Proibição de Polling.
2. Guarde o tra_* e use customId/externalReference para reconciliar com o seu pedido, sem depender da message.
3. Trabalhe sempre em centavos e valide contra os limites (amount entre 500 e 20000000) antes de enviar.
4. Trate o ID como opaco — não tente extrair informação do prefixo nem do sufixo.
5. Use captura manual para valor incerto (reservas, expedição posterior) e capture o valor real, possivelmente parcial.
6. Cobre cartões salvos com payment.card.id, evitando trafegar PAN/CVV — veja Segurança e PCI.
7. Decida por error.code e statusCode: faça retry com backoff em 429, 5xx e paymentProcessingFailed; trate 4xx de negócio sem repetir cegamente.
8. Guarde provas de entrega (rastreio, nota fiscal) desde já — elas são exigidas se a transação virar uma disputa.

Veja também

• Create — criar uma cobrança (cartão, Pix, boleto, Nupay).
• Read — consultar uma transação completa.
• List — listar e filtrar transações.
• Capture — capturar uma pré-autorização.
• Refund — estornar total ou parcialmente.
• Dispute — abrir/registrar uma disputa.
• Convenções · Autenticação · Paginação · Códigos de Erro