Criar um cartão

Visão Geral

Este endpoint permite registrar um novo cartão de crédito ou débito de forma segura, possibilitando armazenar os dados para uso em transações futuras, mediante autorização do titular.

Precauções

ATENÇÃO! Por favor, leia estas informações importantes antes de usar este endpoint.

• 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 armazenados de forma segura para uso em transações futuras.

Requisição

POST /v1/cards

Este endpoint recebe dados completos do cartão (PAN + CVV). Os dados sensíveis (número e código de segurança) são tokenizados e nunca persistidos — apenas os primeiros (BIN) e últimos dígitos são armazenados. Para cobrar usando um cartão já salvo, informe o id do cartão no corpo da transação/assinatura (não neste endpoint).

Corpo da Requisição

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

Parâmetros da Requisição

Observações:

• expirationMonth/expirationYear aceitam números ou strings numéricas. A combinação mês/ano deve ser futura, caso contrário a requisição é rejeitada com cardExpired.
• O campo é primary (não isPrimary).
• Não há campo metadata neste recurso.

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": "2025",
  "primary": true,
  "active": true,
  "valid": true,
  "verified": false,
  "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."
    },
    "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

• 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