Visão geral

Introdução

O recurso de Cartões é um componente fundamental da Selectwin API, permitindo o armazenamento seguro e gerenciamento de informações de meios de pagamento 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, conformidade com padrões PCI DSS e 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 virtuais dentro da plataforma, armazenando de forma segura as informações necessárias para processar transações. 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.

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": "2025",
  "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).
• 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 e Conformidade PCI DSS

A Selectwin API segue rigorosos padrões de segurança para o armazenamento de dados de cartão:

1. Números de cartão completos nunca são armazenados - Apenas os primeiros e últimos dígitos são mantidos para identificação
2. Códigos de segurança (CVV/CVC) nunca são armazenados - São utilizados apenas durante a transação
3. Dados são criptografados - Todas as informações sensíveis são criptografadas em repouso e em trânsito
4. Acesso restrito - Apenas sistemas autorizados podem acessar os dados de cartão
5. Certificação PCI DSS - A plataforma é certificada para garantir a conformidade com os padrões de segurança da indústria

Bandeiras Suportadas

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

Nota: as bandeiras aceitas são configuráveis por ambiente; por padrão a lista acima é aceita. Um cartão de bandeira não reconhecida é detectado como Unknown e a criação é rejeitada com cardBrandNotSupported (HTTP 400).

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