Cartões - Criar

#Visão Geral

Este endpoint permite registrar um novo cartão de crédito de forma segura, possibilitando usá-lo em transações futuras, mediante autorização do titular.

#Precauções

• Segurança: Os dados do cartão são transmitidos de forma segura usando criptografia TLS/SSL.
• Conformidade PCI: Garanta que sua aplicação esteja em conformidade com as diretrizes PCI DSS ao capturar dados de cartões.
• Validação: O sistema realiza validações básicas do número do cartão antes do processamento.
• Tokens: Considere usar tokenização para minimizar o manuseio direto de dados de cartão.

#Descrição

O endpoint Criar Cartão permite cadastrar um novo cartão no sistema, associando-o a um cliente específico. Os dados são validados e o cartão é tokenizado para uso em transações futuras.

#Requisição

POST /v1/cards

#Corpo da Requisição

Forma 1 — token do navegador (recomendada para página própria):

{
  "customerId": "cus_123456789",
  "token": "a1b2c3d4e5f6…",
  "primary": true
}

Forma 2 — dados completos do cartão:

{
  "numbering": "4111111111111111",
  "holderName": "João Silva",
  "expirationMonth": 12,
  "expirationYear": 2030,
  "securityCode": "123",
  "customerId": "cus_123456789",
  "primary": true
}

#Parâmetros da Requisição

#Resposta - 201 Created

Se a requisição for bem-sucedida, um objeto JSON com os detalhes do cartão criado é retornado.

#Exemplo de Resposta

Resposta root (create retorna shape completo de leitura do cartão tokenizado + merchant/_links).

{
  "id": "card_01hqzvabc",
  "holderName": "João Silva",
  "brand": "Visa",
  "firstDigits": "411111",
  "lastDigits": "1111",
  "expirationMonth": "12",
  "expirationYear": "2030",
  "primary": true,
  "active": true,
  "valid": true,
  "verified": false,
  "associated": false,
  "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."
    },
    "delete": {
      "href": "https://api.selectwin.io/v1/cards/card_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the card."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/cards",
      "method": "GET",
      "description": "List all cards."
    }
  }
}

#Atributos da Resposta

Notas:

• O corpo da requisição usa primary; a resposta usa os nomes sem prefixo is (primary, active, valid, verified, associated).
• O recurso de cartão não retorna metadata.
• Cartões são criados com verified: false; a verificação ocorre posteriormente no fluxo de pagamento.

#Respostas de Erro

Todas as respostas de erro seguem o envelope canônico { "error": { status, statusCode, category, code, message, resource, details?, params? } }.

#400 Bad Request - Bandeira não suportada

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "code": "cardBrandNotSupported",
    "message": "Card brand not supported.",
    "resource": "card",
    "details": "The card brand is not supported. Please check the card brand and try again."
  }
}

#400 Bad Request - Cartão expirado

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "code": "cardExpired",
    "message": "Card expired",
    "resource": "card",
    "details": "The provided card has expired. Please use a valid card."
  }
}

#404 Not Found - Cliente inválido

Retornado quando o customerId informado não existe.

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "client",
    "code": "invalidCustomerId",
    "message": "Invalid customer ID.",
    "resource": "customer"
  }
}

#Códigos de erro deste endpoint

#Casos de Uso

1. Checkout em E-commerce: Permitir que o cliente salve um novo cartão durante o processo de compra
2. Registro em Aplicativos: Permitir que usuários adicionem cartões ao se cadastrarem ou posteriormente
3. Subscrições e Recorrências: Adicionar um cartão para cobranças recorrentes futuras
4. Atualização após Expiracao: Substituir um cartão expirado por uma nova versão

#Melhores Práticas

1. Validações no Cliente: Realize validações básicas do número do cartão, data de validade e CVV no frontend antes de enviar para a API
2. Mascaramento de Dados: Mascare os dados do cartão na interface do usuário
3. Criptografia: Utilize conexões seguras (HTTPS) e considere métodos adicionais de criptografia
4. Confirmação do Titular: Implemente métodos para confirmar que o usuário tem permissão para usar o cartão
5. Gestão de Erros: Forneça feedback claro aos usuários quando houver problemas na validação do cartão

#Integração com Outros Endpoints

• Para não lidar com dado de cartão no seu servidor, use a Tokenização no navegador
• Use Listar Cartões para verificar se o cartão foi adicionado com sucesso
• Use Excluir Cartão caso o cliente deseje remover o cartão imediatamente
• Cartões são imutáveis: para alterar dados (ex.: validade), exclua o cartão e cadastre um novo