Cartões - Visão Geral

#Introdução

O recurso de Cartões é um componente fundamental da Selectwin API, permitindo tokenizar e gerenciar os cartões dos clientes. Este recurso possibilita transações online, facilita pagamentos recorrentes e oferece uma experiência de compra simplificada para os usuários finais.

A API de Cartões foi projetada com foco na segurança e na facilidade de integração, permitindo que os desenvolvedores implementem soluções de pagamento robustas e confiáveis.

#Conceito e Funcionalidade

Os cartões representam instrumentos de pagamento tokenizados dentro da plataforma: a sua integração usa a referência (card_...), nunca o número do cartão. Este recurso permite que os clientes salvem seus métodos de pagamento para uso futuro, eliminando a necessidade de inserir dados de cartão repetidamente.

Cada cartão está associado a um cliente específico e pode ser utilizado em diversas operações financeiras, como pagamentos únicos, assinaturas, cobranças recorrentes e reembolsos.

#Autenticação e Base URL

• Base URL: https://api.selectwin.io/v1
• Header de autenticação: SelectKey: sk_test_... (sandbox) ou SelectKey: sk_live_... (produção). O ambiente da chave (live/sandbox) define em qual namespace o cartão é criado e listado.
• Escopos: cards:create, cards:read, cards:list, cards:delete.

#Como um cartão entra

#Estrutura do Objeto Cartão

O objeto Cartão contém informações sobre o instrumento de pagamento, porém com restrições de segurança para proteger dados sensíveis. A estrutura básica inclui:

{
  "id": "card_01hqzvabc",
  "holderName": "João Silva",
  "brand": "Visa",
  "firstDigits": "411111",
  "lastDigits": "1111",
  "expirationMonth": "12",
  "expirationYear": "2030",
  "primary": true,
  "active": true,
  "valid": true,
  "verified": true,
  "associated": true,
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/cards/card_01hqzvabc",
      "method": "GET",
      "description": "Read a card."
    }
  }
}

Notas importantes:

• O objeto de cartão não possui campo metadata.
• As flags de saída usam os nomes primary, active, valid, verified, associated (sem o prefixo is).
• associated pode ser null — ver abaixo.
• brand é retornado capitalizado (ex.: Visa, Mastercard, Amex, Elo), não em minúsculas.
• holderName é normalizado para Title Case na criação (ex.: joão silva → João Silva).
• Exemplos de resposta de recursos individuais incluem merchant + _links. A estrutura de cada item de lista é mais leve (sem merchant/_links por item).

#Recursos Disponíveis

#Segurança

1. Tokenização - A Selectwin tokeniza o cartão: a sua integração nunca precisa guardar dados de cartão, só a referência (card_...)
2. A resposta da API não devolve dados sensíveis - Apenas bandeira e primeiros/últimos dígitos, para identificação
3. Dados protegidos em trânsito - Toda comunicação com a API usa TLS 1.2 ou superior

#Bandeiras Suportadas

A bandeira é detectada automaticamente a partir do número do cartão. A coluna Código é o valor usado na lista de bandeiras aceitas; o campo brand retornado na resposta usa o valor capitalizado.

#Webhooks Acionados

#Casos de Uso Comuns

• Pagamentos Recorrentes: Armazene cartões para cobranças automáticas em assinaturas
• Checkout Simplificado: Permita que clientes utilizem cartões salvos para novas compras
• Marketplace: Armazene cartões para pagamentos a múltiplos vendedores
• Gestão de Métodos de Pagamento: Permita que clientes gerenciem seus cartões salvos
• Transações One-Click: Implemente compras com um clique para melhorar a conversão
• Análise de Risco: Utilize informações de cartão para avaliação de risco nas transações

#Melhores Práticas

1. Sempre valide os dados do cartão antes de enviá-los para a API
2. Utilize tokenização quando disponível para maior segurança
3. Implemente tratamento de erros adequado para lidar com falhas nas requisições
4. Mantenha a interface do usuário atualizada com os cartões disponíveis
5. Verifique a validade dos cartões antes de utilizá-los em transações
6. Ofereça opções para definir cartão padrão para melhorar a experiência do usuário
7. Notifique clientes sobre cartões próximos ao vencimento para evitar falhas em pagamentos futuros

#Solução de Problemas Comuns

#Integração com Outros Recursos

O recurso de Cartões integra-se com:

• Customers: Cartões são associados a clientes específicos através do customerId
• Transactions: Cartões podem ser utilizados em transações para processamento de pagamentos
• Wallets: Cartões podem ser adicionados a carteiras digitais para facilitar pagamentos
• Utils/Card-Bin-Validation: Serviço de validação de BIN para verificação e identificação de cartões
• Simulators: Simulações de pagamento podem ser realizadas com base em informações de cartão

#associated: null — o cartão de porta do comprador antes da 1ª cobrança aprovada

associated diz se o cartão foi associado ao cliente — a validação de valor zero, que pergunta ao emissor se o cartão é bom sem cobrar nada. Quando o cartão entra por uma porta do comprador — o checkout hospedado, o portal do assinante, o cartão enviado em payment.card numa cobrança ou assinatura e o token cunhado no navegador do comprador (também quando salvo pela conta em POST /v1/cards) — esse resultado não é exibido à conta no cartão criado, antes da primeira cobrança aprovada com ele:

A exceção é o token recusado na validação prévia — em POST /v1/cards ou em payment.card.token numa cobrança ou assinatura: a chamada responde 422 cardDeclined e o cartão não é criado (veja os erros em Criar Cartão e em Tokenização no navegador). Gere outro token com outro cartão.

Vale em todos os lugares em que o cartão aparece: GET /v1/cards/:id, GET /v1/cards (inclusive ?holderid=), o cartão embutido em GET /v1/customers/:id e nos eventos customer.*, e os eventos card.created, card.updated e card.expired. O motivo: a validação de valor zero responde "este cartão é válido?" sem cobrança, sem antifraude e sem tarifa — exibida para quem não a fez, vira um verificador de cartão roubado. A venda não depende do campo: a cobrança associa o cartão no caminho governado (antifraude, risco, tarifas) e o resultado dela é o da transação.