Visão geral

O recurso Cartões guarda, de forma tokenizada, os cartões de crédito/débito dos seus clientes para que você possa cobrá-los depois sem precisar manipular os dados sensíveis a cada compra. Tokenizar significa trocar o número do cartão por um identificador opaco (card_...): você passa a referenciar esse token nas cobranças, e o número real do cartão (o PAN) nunca trafega nem fica armazenado no seu sistema.

O que é um cartão na Selectwin

Cada cartão pertence a um cliente (Customer) e funciona como um meio de pagamento reutilizável. Você envia os dados completos do cartão uma vez (no momento da criação); a API os tokeniza e devolve um objeto sem o número completo nem o código de segurança. A partir daí, você usa o id do cartão para cobrar em transações, assinaturas e cobranças recorrentes — sem nunca mais ver ou enviar o número do cartão.

Esse fluxo é o que mantém sua integração dentro do escopo reduzido de conformidade PCI DSS: o dado sensível entra uma vez pelo canal da plataforma e sai como token.

Conceitos importantes:

• Cliente dono (holder): todo cartão é vinculado a um customerId. Um cliente pode ter vários cartões; apenas um pode ser o primário (primary).
• Token opaco: o id (card_...) é um identificador estável e opaco — armazene a string inteira, não faça parsing. Veja Convenções.
• Sem PAN, sem CVV: a resposta expõe só os primeiros (firstDigits) e últimos (lastDigits) dígitos. O número completo e o securityCode nunca são retornados nem armazenados.

Modelo do objeto

Abaixo, o objeto de cartão como retornado por Create e Read (anotado):

{
  "id": "card_01hqzvabc",            // identificador opaco do cartão (token)
  "holderName": "JOÃO SILVA",        // nome impresso no cartão
  "brand": "visa",                   // bandeira detectada a partir do número
  "firstDigits": "411111",           // 6 primeiros dígitos (BIN) — exibição/identificação
  "lastDigits": "1111",              // 4 últimos dígitos — exibição/identificação
  "expirationMonth": "12",           // mês de validade (string na saída)
  "expirationYear": "2025",          // ano de validade (string na saída)
  "primary": true,                   // é o cartão primário do cliente?
  "active": true,                    // token ativo (não excluído)
  "valid": true,                     // passou nas validações (Luhn, etc.)
  "verified": true,                  // verificado junto ao emissor
  "associated": true,                // associado a um cliente
  "updatedAt": "2026-04-12T17:56:33.000Z",
  "createdAt": "2026-04-12T17:56:33.000Z",
  "metadata": {},                    // objeto livre para seus próprios dados
  "merchant": {                      // estabelecimento dono do recurso
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {                        // links HATEOAS para próximas ações
    "self":   { "href": "https://api.selectwin.io/v1/cards/card_01hqzvabc", "method": "GET" },
    "update": { "href": "https://api.selectwin.io/v1/cards/card_01hqzvabc", "method": "PUT" },    // presente na resposta, mas sem operação pública (veja nota abaixo)
    "delete": { "href": "https://api.selectwin.io/v1/cards/card_01hqzvabc", "method": "DELETE" }
  }
}

Campos principais

Ciclo de vida

1. Criação (tokenização). Você envia os dados completos do cartão para POST /v1/cards. A API valida (Luhn, validade, bandeira), tokeniza e devolve o objeto (201). Se os dados não passam, retorna erro (ex.: invalidCardData, cardExpired, cardBrandNotSupported).
2. Uso. Com o cartão ativo, você o referencia pelo id em cobranças (transações, assinaturas). Um cliente pode acumular vários cartões; defina um como primary para usá-lo por padrão.
3. Exclusão. DELETE /v1/cards/{cardId} invalida o token para novas cobranças. É irreversível: para cobrar de novo, é preciso tokenizar o cartão outra vez. Veja Excluir cartão.

Operações

Base URL: https://api.selectwin.io/v1. Todas as chamadas exigem o cabeçalho SelectKey (nunca Authorization: Bearer/Basic) — veja Autenticação.

curl https://api.selectwin.io/v1/cards \
  -H "SelectKey: sl_live_aBcDeFgHiJkLmNoPqRsTuVwXyZ"

Em sandbox, a chave começa com sl_test_.

Bandeira (brand)

O campo brand é preenchido automaticamente pela API a partir do número do cartão — você não o envia na criação. É uma string; os valores observados nas respostas incluem bandeiras como visa, mastercard, american-express, elo, hipercard, diners-club, discover, jcb e aura. Trate brand como rótulo de exibição, não como um enum fechado: use-o para mostrar o ícone correto, mas não codifique regras rígidas em cima de valores específicos. Se a bandeira não for suportada na criação, a API retorna cardBrandNotSupported (422).

Erros

Códigos específicos do recurso Cartões (além dos transversais 401, 403, 422, 429, 500). Trate sempre pelo error.code, nunca pela message — veja o Catálogo de Códigos de Erro.

Boas práticas

• Tokenize uma vez, cobre muitas. Crie o cartão uma única vez e reutilize o id nas cobranças. Nunca guarde o número completo do cartão no seu lado.
• Nunca exiba o PAN. Para mostrar o cartão na sua interface, use brand + lastDigits (ex.: "Visa •••• 1111"). É só o que a API devolve, e é suficiente.
• Trate as duas formas das flags. primary/active/… em Create e Read; isPrimary/isActive/… na listagem. Normalize no seu código para evitar undefined.
• Defina um cartão primário. Marque um cartão como primary: true para usá-lo por padrão e melhorar a experiência de checkout.
• Antecipe o vencimento. Compare expirationMonth/expirationYear com a data atual e peça um novo cartão antes que falhe uma cobrança recorrente.
• Garanta a posse antes de cobrar. O cartão e o cliente da cobrança precisam ser do mesmo estabelecimento, senão você verá cardAndCustomerOfCompanyNotSame.
• Use idempotência na criação. Envie X-Idempotency-Key no POST para não tokenizar o mesmo cartão duas vezes em caso de retry — veja Idempotência.
• Trate erros pelo code. Decida o fluxo (pedir outro cartão, reverificar dados) com base no error.code, não na mensagem.

Relações com outros recursos

• Customers: todo cartão pertence a um cliente, referenciado por customerId na criação.
• Transactions: o cartão tokenizado é o meio de pagamento usado para processar cobranças.
• Subscriptions: cartões salvos viabilizam cobranças recorrentes em assinaturas.

Veja também

• Criar cartão
• Consultar cartão
• Listar cartões
• Excluir cartão
• Convenções · Autenticação · Idempotência · Paginação · Catálogo de Códigos de Erro