> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Desativar cartão
> Desativa um cartão salvo — ele sai da listagem e deixa de poder ser cobrado.
`DELETE /customers/{customerId}/cards/{cardId}`
Faz parte do recurso [Cartões](/pt-BR/cards) — como um cartão é salvo e como cobrá-lo estão lá.
Desativa o cartão. Ele sai da [listagem](/pt-BR/cards/list), o `GET` por ID passa a responder `404`
e o `crd_` deixa de servir para cobrar.
**A resposta é a última vez que você vê o cartão**, e ela vem com `status: "disabled"`. Se você
registra a desativação do seu lado, é daqui que o dado sai — depois desta chamada, nenhuma rota
devolve esse `crd_`.
**Não há rota de reativação — mas salvar o mesmo cartão o reativa.** Se o cliente informar o
mesmo cartão de novo (um token novo do [Tokenizer](/pt-BR/tokenizer), mesmos dados), a impressão
digital casa com o registro desativado e ele **volta ativo, com o mesmo `crd_`**. Cartão
diferente gera um `crd_` novo. Trate a desativação como "parar de cobrar", não como apagar: o
reenvio do próprio cartão pelo cliente desfaz.
**O histórico não muda.** Transações e pagamentos feitos com aquele cartão continuam existindo e
guardam os dados usados na cobrança. Desativar é sobre o uso futuro, não sobre o passado.
Endpoint idempotente. Envie o header `Idempotency-Key` — desativar duas vezes por um retry não é
problema, mas a segunda chamada sem a chave responderia `404`, já que o cartão não é mais
encontrado.
## OpenAPI
````yaml openapi/psp.json DELETE /customers/{customerId}/cards/{cardId}
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/customers/{customerId}/cards/{cardId}:
delete:
tags:
- Cards
summary: Desativar cartão
description: >-
Desativa um cartão salvo do cliente. Ele sai da listagem e passa a
responder 404; a resposta traz status disabled
operationId: CardController_disable
parameters:
- name: cardId
in: path
required: true
description: ID do cartão
schema:
type: string
- name: customerId
in: path
required: true
description: ID do cliente
schema:
type: string
- name: Idempotency-Key
in: header
required: false
description: Chave única para garantir idempotência da requisição
schema:
type: string
responses:
'200':
description: Cartão desativado
content:
application/json:
example:
id: crd_hqx4mkpi8dcxbrb2nzynxnjky
customerId: cust_j43n74fbt2geb8c1y86ssf6iw
brand: visa
firstDigits: '411111'
lastDigits: '1111'
holderName: JOAO DA SILVA
expirationMonth: '12'
expirationYear: '2030'
status: disabled
createdAt: '2026-07-02T19:26:17.000Z'
updatedAt: '2026-07-02T20:10:42.000Z'
schema:
type: object
properties:
id:
type: string
description: ID do cartão (`crd_`).
customerId:
type: string
description: Cliente dono do cartão (`cust_`).
brand:
type: string
description: 'Bandeira (ex.: `visa`, `mastercard`).'
firstDigits:
type: string
description: Seis primeiros dígitos.
lastDigits:
type: string
description: Quatro últimos dígitos.
holderName:
type: string
description: Nome impresso no cartão.
expirationMonth:
type: string
description: Mês de validade (`MM`).
expirationYear:
type: string
description: Ano de validade (`YYYY`).
status:
type: string
description: Situação do cartão.
createdAt:
type: string
description: Criação, ISO 8601.
updatedAt:
type: string
description: Última alteração, ISO 8601.
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'404':
description: Cartão não encontrado
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: NOT_FOUND
message: Card not found
'409':
description: >-
Já existe uma requisição em andamento com esta Idempotency-Key. A
API aguarda a primeira concluir por até 5 segundos antes de
responder assim
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: A request with this idempotency key is already being processed
'422':
description: >-
Idempotency-Key já usada com um corpo diferente. Use uma chave nova
para uma operação diferente
content:
application/json:
schema:
type: object
properties:
error:
type: string
description: >-
Mensagem do conflito de idempotência. Aqui `error` é
texto, não objeto — ramifique pelo status HTTP.
example:
error: Idempotency key already used with a different request body
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````