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": "https://selectwin.io/invoices/tra_01hqzvabc"
  },
  "discount": null,
  "discounts": null,
  "customer": {
    "id": "cus_987654321",
    "firstName": "Maria",
    "lastName": "Silva",
    "email": "[email protected]",
    "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:

O alias unauthorized não é um status produzido pela API — ele é aceito apenas como filtro em Listar.

Fluxo de Status da Transação

Fluxo de Status dos Recebíveis

Métodos de Pagamento Suportados

A API suporta os seguintes métodos de pagamento:

A criação de transações suporta apenas credit, pix e billet. Os identificadores debit e nupay não são aceitos na criação (nupay aparece apenas como filtro em Listar, por compatibilidade com dados legados).

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 (recebível, saldo e antifraude próprios) e a plataforma recolhe sua taxa de aplicação como um split adicional.

Webhooks Acionados

Não existe transaction.refused (use transaction.failed) nem eventos transaction.method.* / receivable.deleted. A lista completa de eventos está no Catálogo de Eventos.

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