> ## Documentation Index > Fetch the complete documentation index at: https://docs.usevext.com/llms.txt > Use this file to discover all available pages before exploring further. # Remover cartão guardado > Revoga um cartão do cofre sem apagar o histórico das cobranças que ele pagou. Remover **revoga**, e a linha fica. Um cartão apagado de vez deixaria de responder "com que cartão foi aquela cobrança de março?", que é justamente a pergunta de quem tira do ar uma credencial sob suspeita. A partir daqui, cobrar com este `pm_` volta `422 card_revoked`. ## OpenAPI ````yaml api-reference/openapi.yaml DELETE /v1/cards/{code} openapi: 3.1.0 info: title: Vext - API de pagamentos PIX com split version: 1.0.0 summary: Cobranças PIX, estornos e saldo do vendedor. description: | API pública do gateway. Todo endpoint desta versão vive sob `/v1`. ## Dinheiro é sempre CENTAVOS INTEIROS Não há exceção. `amount`, `platform_fee`, `net_amount`, `refunded_amount`, `fee_returned`, `seller_debit`, `balance`, `available`, `reserved`, `debt` e `withdrawable` são inteiros em centavos de real. | Valor | Envie / receba | |-------------|----------------| | R$ 1,00 | `100` | | R$ 10,50 | `1050` | | R$ 1.234,56 | `123456` | Enviar `10.50` devolve `422`. A recusa é deliberada: `10.50` chega ao servidor como ponto flutuante, `10.50 * 100` não é exatamente `1050` em binário, e o centavo perdido só aparece na conciliação do mês. Diante de um decimal preferimos recusar a adivinhar a intenção - com dinheiro, adivinhar sai caro. ## Autenticação Toda chamada leva a chave no header: ``` Authorization: Bearer sk_live_SUA_CHAVE_SECRETA ``` A chave é criada em **Desenvolvedores** no painel e o valor em claro aparece **uma única vez**, na criação - guardamos apenas um hash SHA-256. Perdeu, gere outra. Cada chave carrega escopos (`charges:read`, `charges:write`, `refunds:write`, `balance:read`, `cards:manage`). Chamar um endpoint fora do escopo devolve `403`, e não `401`: a chave está certa, faltou permissão. Chaves de teste usam o prefixo `sk_test_`. A diferença é visível a olho nu de propósito - uma chave de teste colada em produção precisa ser reconhecível antes de alguém passar a tarde investigando. ## Idempotência Envie `Idempotency-Key` em todo `POST`. A conexão que cai depois da requisição e antes da resposta deixa você sem saber se cobrou; repetir com a mesma chave resolve isso sem risco de cobrar duas vezes. - **mesma chave, mesmo corpo** → a resposta gravada, com `Idempotent-Replayed: true`. A cobrança não é recriada. - **mesma chave, corpo diferente** → `409 idempotency_key_reused`. Devolver a cobrança antiga faria você acreditar que cobrou o valor novo. - **mesma chave, primeira ainda em voo** → `409 idempotency_key_in_progress`. Repita em instantes. A ordem dos campos no JSON não invalida o retry. A chave vale por 24 horas e é sua: dois clientes diferentes podem usar `pedido-1` sem colidir. ## Erros Todo erro - inclusive os que não previmos - tem a mesma forma: ```json { "error": { "type": "invalid_request_error", "code": "amount_below_minimum", "message": "…", "details": {} } } ``` Trate pelo `code`, nunca pela `message`: o código é contrato, o texto pode ser reescrito a qualquer momento. contact: name: Suporte Vext url: https://wa.me/5511936185272 servers: - url: https://api.usevext.com description: Produção security: - apiKey: [] tags: - name: Cobranças description: Criação, consulta e estorno de cobranças, no PIX e no cartão. - name: Saldo description: Quanto o vendedor tem e quanto pode sacar. - name: Cartões description: | Os cartões que os compradores deixaram guardados, para cobrar de novo sem pedir nada a eles. paths: /v1/cards/{code}: delete: tags: - Cartões summary: Remover cartão guardado description: | Revoga o cartão. **A linha fica**: um cartão apagado não responde "com que cartão foi aquela cobrança de março?", que é exatamente a pergunta de quem remove uma credencial suspeita. A partir daqui, cobrar com este `pm_` devolve `422 card_revoked`. operationId: deleteSavedCard parameters: - $ref: '#/components/parameters/SavedCardCode' responses: '200': description: O cartão, agora revogado. content: application/json: schema: $ref: '#/components/schemas/SavedCard' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' security: - apiKey: - cards:manage components: parameters: SavedCardCode: name: code in: path required: true description: Código público do cartão guardado, no formato `pm_…`. schema: type: string pattern: ^pm_[0-9a-z]{26}$ example: pm_01k1y6r6m6q2x0p3d9v4t7c8n2 schemas: SavedCard: type: object description: | Um cartão guardado. **Todo campo está sempre presente.** O que NÃO está aqui, e não vai estar: as referências da Pagar.me que de fato cobram, e os seis primeiros dígitos. As primeiras são o equivalente ao cartão para quem as tem; o BIN somado aos quatro últimos é material de correlação que você não precisa. required: - object - id - brand - last_four - exp_month - exp_year - holder_name - expired - created_at - last_used_at properties: object: type: string const: card id: type: string pattern: ^pm_[0-9a-z]{26}$ brand: type: - string - 'null' enum: - visa - mastercard - elo - hipercard - amex - diners - discover - aura - null last_four: type: - string - 'null' exp_month: type: - integer - 'null' minimum: 1 maximum: 12 exp_year: type: - integer - 'null' holder_name: type: - string - 'null' expired: type: boolean description: | Vencido é ESTADO, e não ausência: o cartão continua na lista para você entender por que a cobrança de um clique parou de funcionar para aquele comprador. created_at: type: - string - 'null' format: date-time last_used_at: type: - string - 'null' format: date-time Error: type: object required: - error properties: error: type: object required: - type - code - message - details properties: type: type: string description: | Família do erro. Responde "de quem é o problema e o que fazer": `invalid_request_error` se corrige mudando a chamada, `authentication_error` trocando a chave, e `api_error` é nosso - repita, não reescreva. enum: - authentication_error - permission_error - invalid_request_error - idempotency_error - not_found_error - rate_limit_error - api_error - card_error code: type: string description: | Código estável do erro. **Trate por ele.** A `message` pode ser reescrita a qualquer momento; o código, não. message: type: string description: Explicação em português, para leitura humana. details: type: object description: | Sempre objeto, mesmo vazio. Em `validation_failed`, traz os campos recusados e suas mensagens. additionalProperties: true responses: Unauthorized: description: | Chave ausente, desconhecida, revogada ou expirada. A revogada é distinguida da inexistente na MENSAGEM, nunca no status: quem integra precisa saber que a chave existiu e foi desligada, e quem está adivinhando tokens não aprende nada com isso. content: application/json: schema: $ref: '#/components/schemas/Error' examples: ausente: summary: missing_api_key value: error: type: authentication_error code: missing_api_key message: 'Envie a chave em Authorization: Bearer sk_live_...' details: {} invalida: summary: invalid_api_key value: error: type: authentication_error code: invalid_api_key message: Chave de API inválida. details: {} revogada: summary: revoked_api_key value: error: type: authentication_error code: revoked_api_key message: >- Esta chave de API foi revogada. Gere uma nova em Desenvolvedores. details: {} expirada: summary: expired_api_key value: error: type: authentication_error code: expired_api_key message: Esta chave de API expirou. Gere uma nova em Desenvolvedores. details: {} Forbidden: description: | A chave é válida, mas não tem o escopo do endpoint. `403` e não `401` de propósito: `401` diria "sua chave está errada" a quem tem a chave certa. content: application/json: schema: $ref: '#/components/schemas/Error' examples: escopo: summary: insufficient_scope value: error: type: permission_error code: insufficient_scope message: Esta chave não tem o escopo [refunds:write]. details: required_ability: refunds:write abilities: - charges:read - charges:write umClique: summary: one_click_requires_three_ds value: error: type: permission_error code: one_click_requires_three_ds message: >- Esta loja exige autenticação do portador, e o pagamento de um clique não a suporta. details: {} NotFound: description: | O recurso não existe - ou é de outra conta, o que daqui dá no mesmo. Não distinguimos os dois casos: responder "existe, mas não é seu" confirmaria a existência de cobranças alheias a quem tentasse adivinhar códigos. content: application/json: schema: $ref: '#/components/schemas/Error' examples: naoEncontrado: value: error: type: not_found_error code: resource_not_found message: Recurso não encontrado. details: {} RateLimited: description: | Requisições demais. Há três limites, por minuto: um por IP antes da autenticação, e depois um de leitura e um de escrita, ambos por CHAVE - o excesso de uma integração não consome a cota das outras do mesmo vendedor. A escrita é bem mais apertada porque cada cobrança criada vira uma chamada ao provedor. `Retry-After` diz em quantos segundos voltar. Os cabeçalhos `X-RateLimit-*` vêm em TODA resposta, não só nesta: são eles que permitem desacelerar antes de bater no limite. headers: Retry-After: description: Segundos até a cota ser reposta. schema: type: integer X-RateLimit-Limit: description: Requisições permitidas por minuto neste balde. schema: type: integer X-RateLimit-Remaining: description: Quantas ainda cabem no minuto corrente. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' examples: cota: summary: too_many_requests value: error: type: rate_limit_error code: too_many_requests message: Muitas requisições. Tente novamente em 42 segundos. details: retry_after: 42 provedor: summary: provider_rate_limited value: error: type: rate_limit_error code: provider_rate_limited message: >- Limite de requisições do provedor atingido. Tente novamente em instantes. details: {} securitySchemes: apiKey: type: http scheme: bearer bearerFormat: sk_live_… | sk_test_… description: | Chave secreta do vendedor, criada no painel em **Desenvolvedores**. O valor em claro existe uma única vez, na criação. Guardamos só o hash SHA-256 - nem o suporte consegue recuperá-lo, o que é o ponto: um dump do nosso banco não permite cobrar em nome de ninguém. A chave vai no **servidor**. Colocá-la no navegador do comprador a entrega a qualquer pessoa que abra a página. ````