Excluir um cartão

Remove permanentemente um cartão tokenizado da conta, identificado pelo seu cardId. Use quando o cliente pedir para apagar um meio de pagamento, quando um cartão estiver comprometido ou ao limpar cartões obsoletos. A operação é irreversível e invalida o token para novas cobranças.

DELETE /v1/cards/{cardId}

Como funciona

A Selectwin nunca armazena o número completo do cartão (o PAN). No cadastro, os dados sensíveis são trocados por um token — uma referência opaca (card_…) usada nas cobranças. "Excluir um cartão" significa invalidar esse token: depois da exclusão ele deixa de existir para a conta e não pode mais ser usado para novas transações.

Pontos importantes sobre o mecanismo:

• É irreversível. Não há "lixeira" nem restauração. Para usar o mesmo cartão de novo, é preciso cadastrá-lo outra vez via Criar cartão — o que gera um novo card_….
• Não afeta cobranças passadas. Transações já criadas com esse cartão continuam existindo e seguem seu próprio ciclo de vida (captura, estorno, disputa). Excluir o cartão não cancela nem estorna nada que já foi cobrado.
• Síncrona. A resposta já confirma o resultado; não há processamento assíncrono nem evento de webhook obrigatório para concluir a operação.
• Idempotente por natureza. O efeito é "este cartão não existe mais". Repetir o DELETE no mesmo cardId já removido não cria efeitos adicionais — a segunda chamada apenas não encontra o cartão e responde com erro de não encontrado (veja Erros).

Quando usar (e quando não)

Use o DELETE quando o objetivo for realmente remover o meio de pagamento:

• O cliente pediu para apagar o cartão.
• O cartão foi comprometido (suspeita de fraude) e deve ser invalidado.
• Limpeza de cartões expirados ou não utilizados após o cliente cadastrar um novo.

Quando não usar:

• Só quer consultar antes de decidir? Use Consultar cartão ou Listar cartões — eles não alteram nada.
• Quer apenas trocar o cartão padrão? Você não precisa excluir o antigo: cadastre o novo com primary: true em Criar cartão.
• Precisa do cartão novamente depois? Lembre-se de que a exclusão é definitiva — reativar exige um novo cadastro e gera um novo ID.

Requisição

Headers

Não há corpo de requisição, então Content-Type é dispensável aqui. Veja Autenticação para detalhes da SelectKey.

Como é uma operação destrutiva e idempotente, o cabeçalho X-Idempotency-Key é opcional — o efeito final ("cartão removido") não muda ao repetir a chamada. Veja Idempotência.

Parâmetros de caminho

Exemplo de requisição

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

Resposta

Em caso de sucesso, a API retorna 200 OK com um objeto de confirmação. O campo deleted: true é a sinalização canônica de que o token foi invalidado; o bloco _links (HATEOAS) traz os próximos passos possíveis (criar outro cartão, listar os cartões restantes).

{
  "id": "card_01hqzvabc",
  "resource": "card",
  "deleted": true,
  "merchant": {
    "name": "Seller Name",
    "merchantId": "bus_1234567890",
    "isSubAccount": false
  },
  "_links": {
    "self": {
      "href": "https://api.selectwin.io/v1/cards/card_01hqzvabc",
      "method": "DELETE",
      "description": "Delete the card."
    },
    "create": {
      "href": "https://api.selectwin.io/v1/cards",
      "method": "POST",
      "description": "Create a new card."
    },
    "list": {
      "href": "https://api.selectwin.io/v1/cards",
      "method": "GET",
      "description": "List all cards."
    }
  }
}

Campos da resposta

Erros

Em caso de falha, a API retorna o envelope de erro padrão com um error.code estável (faça o tratamento pelo code, nunca pela message). Veja Tratamento de Erros e o Catálogo de Códigos de Erro.

Exemplo de resposta 404 (cartão inexistente ou já excluído):

{
  "error": {
    "code": "cardNotFound",
    "statusCode": 404,
    "category": "client",
    "message": "Card not found"
  }
}

Boas práticas

• Confirme com o usuário. Por ser irreversível, peça confirmação explícita antes de disparar o DELETE.
• Cheque o cartão principal. Antes de excluir, verifique se o cartão é o principal — o campo varia conforme o endpoint: em List é isPrimary (em data[]) e em Read é primary. Se for o principal, defina outro como primary (via Criar cartão com primary: true) para não deixar o cliente sem meio padrão.
• Guarde os dados que precisar antes. Como a resposta de exclusão é enxuta, leia o cartão antes se você registra brand/lastDigits para auditoria ou exibição.
• Registre a exclusão. Mantenha um log (quem, quando, qual cardId) para auditoria e suporte.
• Trate o erro pelo error.code. Use cardNotFound/cardIdIsInvalid para mensagens claras ao usuário; reserve retry com backoff para 429 e 5xx.
• Não confie em estado em cache. Após excluir, invalide qualquer referência local ao cardId; cobranças futuras com ele falharão.

Veja também

• Visão geral de Cartões — o objeto, o ciclo de vida e todas as operações.
• Criar cartão — cadastrar/tokenizar um novo cartão (e definir o principal).
• Consultar cartão — ver os detalhes antes de excluir.
• Listar cartões — encontrar todos os cartões de um cliente.
• Convenções da API e Autenticação.