Transações - Visão Geral

#Introdução

O recurso de Transações é um componente central da Selectwin API, permitindo o processamento e gerenciamento completo de pagamentos em sua plataforma. Este recurso oferece funcionalidades robustas para criar, consultar, capturar, reembolsar e disputar transações, com suporte a diversos métodos de pagamento como cartão de crédito, boleto, PIX e outros, atendendo às necessidades de diferentes modelos de negócio.

A API de Transações foi projetada com foco na versatilidade, segurança e rastreabilidade, proporcionando uma solução completa para o processamento de pagamentos em ambientes de e-commerce, marketplaces e serviços por assinatura.

#Estrutura do Objeto Transação

O objeto Transação contém informações detalhadas sobre o pagamento, cliente, itens, status e histórico. A estrutura básica inclui:

{
  "id": "tra_01hqzvabc",
  "customId": "E5D4C3B2A1",
  "amount": 1500,
  "originalAmount": 1500,
  "status": "approved",
  "method": "credit",
  "currency": "BRL",
  "payment": {
    "provider": "selectwin",
    "version": "1.1",
    "reusable": false,
    "cardFirstDigits": "553121",
    "cardLastDigits": "4567",
    "cardBrand": "Mastercard",
    "cardRegistered": true,
    "installments": 3,
    "acquirerTransactionNumber": "9876543210987654321098765432",
    "paidAt": "2026-03-10T14:23:45.000Z",
    "invoiceLink": null
  },
  "discount": null,
  "discounts": null,
  "customer": {
    "id": "cus_987654321",
    "firstName": "Maria",
    "lastName": "Silva",
    "email": "maria.silva@exemplo.com",
    "document": { "type": "cpf", "number": "98765432100" }
  },
  "billing": { "address": { "street": "Avenida Paulista", "number": "2000", "city": "São Paulo", "state": "SP", "postcode": "01310200", "country": "BR" } },
  "shipping": null,
  "externalReference": "CUS_REF_123",
  "shippable": true,
  "spplited": false,
  "items": [
    { "id": "item_123", "name": "Produto Exemplo", "quantity": 1, "unitPrice": 1500, "currency": "BRL" }
  ],
  "receivables": [],
  "splits": null,
  "refunds": null,
  "disputes": null,
  "timeline": [
    {
      "id": "tl_123",
      "message": "Transaction approved",
      "type": "status_change",
      "createdAt": "2026-03-10T14:23:45.000Z"
    }
  ],
  "metadata": { "segment": "regular" },
  "updatedAt": "2026-03-10T14:00:30.000Z",
  "createdAt": "2026-03-10T09:15:25.000Z"
}

Nota: Esta é uma versão resumida. A resposta completa (nível raiz) inclui merchant e _links (self, refund, capture). O customer traz os dados do comprador, mas não embute addresses/cards (use GET /v1/customers/:id); billing.address é aninhado. Para o exemplo completo e fiel, consulte Create / Read. A listagem usa projeção leve (ver List).

#Status de Transação

Uma transação pode passar por diversos status durante seu ciclo de vida:

#Fluxo de Status da Transação

stateDiagram-v2
    state "fraud-review" as fraud
    state "pending" as pending
    state "pre-authorized" as preauth
    state "approved" as approved
    state "failed" as failed
    state "dispute" as dispute
    state "chargeback" as chargeback
    state "refunded" as refunded
    state "canceled" as canceled

    [*] --> pending: POST /v1/transactions
    [*] --> fraud: retida para análise de fraude
    fraud --> pending: revisão aprovada
    fraud --> failed: revisão reprovada
    pending --> preauth: crédito · capture=false
    pending --> approved: crédito aprovado · PIX ou boleto pago
    pending --> failed: recusada
    pending --> canceled: PIX vencido sem pagamento
    canceled --> approved: PIX pago depois do vencimento
    preauth --> approved: POST .../capture
    preauth --> canceled
    approved --> refunded: POST .../refund
    approved --> dispute: contestação do titular
    approved --> chargeback
    dispute --> chargeback
    dispute --> approved: disputa ganha
    failed --> [*]
    canceled --> [*]
    refunded --> [*]
    chargeback --> [*]

• Toda cobrança nasce pending (ou fraud-review, quando fica retida para análise). A recusa termina em failed.
• Só o PIX vencido é cancelado automaticamente. O boleto fica pending até o vencimento, e o vencimento sozinho não muda o status: a Selectwin não cancela boleto vencido. Depois do vencimento ele continua pending até chegar um desfecho — pago, inclusive com atraso, vira approved (transaction.approved); baixado, vira canceled (transaction.canceled). Sem desfecho, continua pending.
• A defesa de uma disputa é POST /v1/transactions/{id}/dispute (veja Disputar); ela não abre a disputa, que começa quando a contestação chega.
• awaiting e analyzing são estados intermediários fora do caminho principal: trate-os como pendentes, e o desfecho chega pelo webhook.

#Fluxo de Status dos Recebíveis

stateDiagram-v2
    state "scheduled" as scheduled
    state "pending" as pending
    state "paid" as paid
    state "dispute" as dispute
    state "chargeback" as chargeback
    state "refunded" as refunded
    state "canceled" as canceled

    [*] --> scheduled: recebível gerado (expectedOn futuro)
    [*] --> pending: aguardando liquidação
    scheduled --> paid: na data prevista
    pending --> paid: liberado
    scheduled --> canceled
    pending --> canceled
    paid --> refunded: transação reembolsada
    paid --> dispute: contestação
    dispute --> chargeback
    dispute --> paid: disputa resolvida
    paid --> [*]
    refunded --> [*]
    chargeback --> [*]
    canceled --> [*]

#Métodos de Pagamento Suportados

A API suporta os seguintes métodos de pagamento:

#Recursos Disponíveis

#Criar Transação

• Endpoint: POST /v1/transactions
• Descrição: Cria uma nova transação (credit, pix ou billet). Retorna 201 (ou 202 em análise de fraude)
• Documentação detalhada

#Consultar Transação

• Endpoint: GET /v1/transactions/{transactionId}
• Descrição: Obtém os detalhes completos de uma transação
• Documentação detalhada

#Listar Transações

• Endpoint: GET /v1/transactions
• Descrição: Lista paginada com filtros (projeção leve)
• Documentação detalhada

#Capturar Transação

• Endpoint: POST /v1/transactions/{transactionId}/capture
• Descrição: Captura uma transação pré-autorizada (assíncrono, HTTP 202)
• Documentação detalhada

#Reembolsar Transação

• Endpoint: POST /v1/transactions/{transactionId}/refund
• Descrição: Reembolsa uma transação aprovada, total ou parcialmente (assíncrono, HTTP 202)
• Documentação detalhada

#Disputar Transação (defesa)

• Endpoint: POST /v1/transactions/{transactionId}/dispute
• Descrição: Submete evidências para defender uma transação em disputa
• Documentação detalhada

#Funcionalidades Avançadas

#Captura Manual vs Automática

A API permite dois modos de captura para transações com cartão de crédito:

• Captura Automática (capture: true): O valor é capturado imediatamente após a autorização
• Captura Manual (capture: false): O valor é apenas pré-autorizado e deve ser capturado posteriormente via endpoint específico

A captura manual é ideal para:

• Reservas hoteleiras
• Aluguel de veículos
• Serviços com valor final indefinido
• Verificação de fundos sem cobrança imediata

#Financiamento automático de parcelas

Em cobranças com cartão de crédito parceladas (installments > 1), o campo payment.financeInstallments (default true) faz a API financiar automaticamente o parcelamento: o valor base é inflado para o total que o comprador pagaria com os juros configurados pelo vendedor (mesmo motor do simulador). Envie false apenas quando você já tiver calculado e enviado o total financiado.

#Cobrança em nome de sub-conta (marketplace)

Plataformas de marketplace podem cobrar diretamente em nome de uma sub-conta que possuem usando onBehalfOf (o publicId da sub-conta). A sub-conta passa a ser o merchant de registro e a plataforma recolhe sua taxa de aplicação como um split adicional.

Por pertencer à sub-conta, essa venda é consultada, capturada e estornada como a sub-conta: envie X-Selectwin-Account: bus_… junto da sua chave — veja Operar como a sub-conta. A plataforma recebe os webhooks dela (transaction.*) com o campo account.

#Webhooks Acionados

#Casos de Uso Comuns

• E-commerce: Processamento de pagamentos para lojas virtuais
• Assinaturas: Cobranças recorrentes para serviços de assinatura
• Marketplace: Processamento de pagamentos para múltiplos vendedores
• Aplicativos Móveis: Integração de pagamentos em aplicativos
• Pontos de Venda: Integração com sistemas de PDV físicos

#Melhores Práticas

1. Sempre utilize webhooks para receber notificações de mudanças de status
2. Armazene o ID da transação para consultas e operações futuras
3. Utilize a referência externa para facilitar a reconciliação com seu sistema
4. Implemente tratamento de erros adequado para lidar com falhas nas requisições
5. Para transações de alto valor, considere utilizar captura manual
6. Mantenha registros detalhados para facilitar a resolução de disputas

#Integração com Outros Recursos

O recurso de Transações integra-se com:

• Customers: Transações são associadas a clientes através do customer.id ou dados completos do cliente
• Cards: Cartões salvos podem ser utilizados em transações através do payment.card.id
• Simulators: Ferramentas de simulação para testar diferentes cenários de pagamento
• Webhooks: Notificações em tempo real sobre mudanças de status nas transações