Cartões

Visão Geral

Os Cartões (Cards) são os cartões salvos de um cliente. Um cartão pertence sempre a um cliente (identificado pelo clientCode na URL) e pode ser reutilizado em cobranças e assinaturas sem que o portador precise digitar os dados novamente. Ao salvar um cartão, ele é tokenizado de forma assíncrona. A tokenização acontece em segundo plano e não bloqueia a resposta: o endpoint responde imediatamente com tokenization_status: "pending" e o resultado é entregue por webhook (card.token_created / card.token_failed).

Por segurança (PCI), o número completo do cartão (PAN) e o código de segurança (CVV) nunca são retornados pela API. As respostas expõem apenas os seis primeiros e os quatro últimos dígitos (first_six_digits / last_four_digits).

Header obrigatório

Todas as rotas de cartões exigem o header account com o código da conta:

account: acc_abc123xyz

O cliente é identificado pelo clientCode na própria URL (ex.: cli_abc123), e o cartão pelo seu id (UUID).

Formato de resposta padrão

As rotas de cartões seguem o envelope padrão APIReturnUtil:

{
  "mensagem": "Mensagem descritiva",
  "erro": false,
  "mensagenserro": [],
  "codigoretorno": 200,
  "id": "00000000-0000-0000-0000-000000000000",
  "data": { ... }
}

Campo	Tipo	Descrição
`mensagem`	string	Mensagem descritiva da operação
`erro`	boolean	`false` em caso de sucesso, `true` em caso de erro
`mensagenserro`	array	Lista de mensagens de erro (vazia em caso de sucesso)
`codigoretorno`	integer	Código HTTP de retorno
`id`	string	ID do recurso afetado ou GUID vazio
`data`	mixed	Objeto do cartão, ou `{ "cards": [...] }` na listagem

Objeto do cartão

Campo	Tipo	Descrição
`id`	string	UUID identificador do cartão
`card_token`	string	Identificador do cartão salvo — enviado em `payment.card.card_token` ao cobrar
`first_six_digits`	string	Seis primeiros dígitos do cartão (BIN)
`last_four_digits`	string	Quatro últimos dígitos do cartão
`brand`	string	Bandeira: `visa`, `mastercard`, `elo`, `amex` ou `undefined`
`holder_name`	string	Nome do portador impresso no cartão
`exp_month`	integer	Mês de validade (`1`–`12`)
`exp_year`	integer	Ano de validade (`YYYY`)
`type`	string	Tipo do cartão: `credit` ou `debit`
`status`	string	`active` ou `deleted`
`tokenization_status`	string	`pending`, `tokenized` ou `failed`
`created_at`	string	Data de criação (ISO 8601)
`updated_at`	string	Data da última atualização (ISO 8601)
`deleted_at`	string	Data de exclusão (ISO 8601) — presente apenas em cartão excluído

Status de um cartão

Status	Descrição
`active`	Cartão ativo e disponível para uso
`deleted`	Cartão excluído (soft delete) — não pode ser usado

Campos de cadastro

Campo	Tipo	Req.	Descrição
`name`	string	Sim	Nome do portador impresso no cartão (máx. 255)
`number`	string	Sim	Número do cartão (13–19 dígitos, validado por Luhn)
`month`	integer	Sim	Mês de validade (`1`–`12`)
`year`	integer	Sim	Ano de validade (2 ou 4 dígitos; deve estar no futuro)
`security_code`	string	Sim	Código de segurança (CVV, 3 ou 4 dígitos)
`type`	string	Não	`credit` (padrão) ou `debit`
`flag`	string	Não	Bandeira: `visa`, `mastercard`, `elo`, `amex`

Na atualização, apenas name, type, flag, month e year podem ser alterados — month e year devem ser enviados juntos. O número e o código de segurança são imutáveis: para trocá-los, cadastre um novo cartão.

Tokenização

Ao salvar um cartão (POST .../cards/tokens) — ou ao alterar sua validade — a plataforma inicia a tokenização em segundo plano. A resposta é imediata, com tokenization_status: "pending", e o resultado é comunicado por webhook:

Evento	Significado
`card.created`	O cartão foi salvo.
`card.token_pending`	A tokenização foi iniciada.
`card.token_created`	O cartão está tokenizado e pronto para cobranças.
`card.token_failed`	Não foi possível tokenizar o cartão.

Aguarde o card.token_created antes de usar o cartão em uma cobrança. Consulte os payloads em Webhooks → Eventos → Cartão.

Exclusão

A exclusão de um cartão é um soft delete: o registro passa a ter status deleted e deleted_at preenchido, e seus tokens são removidos. Um evento card.deleted é emitido.

Um cartão vinculado a uma assinatura ativa não pode ser excluído — a API retorna 409 Conflict. Altere o cartão da assinatura antes de excluir.

Exemplo completo

Salvar cartão (request)

{
  "name": "Tony Stark",
  "number": "5425011234567793",
  "month": 1,
  "year": 2030,
  "security_code": "123",
  "type": "credit",
  "flag": "mastercard"
}

Resposta (HTTP 202)

{
  "mensagem": "Cartão recebido. A tokenização foi iniciada; o resultado será enviado por webhook.",
  "erro": false,
  "mensagenserro": [],
  "codigoretorno": 202,
  "id": "00000000-0000-0000-0000-000000000000",
  "data": {
    "id": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "card_token": "9b2f5c8e-3a1d-4f7b-8c6e-2d9a1b4c5e6f",
    "first_six_digits": "542501",
    "last_four_digits": "7793",
    "brand": "mastercard",
    "holder_name": "Tony Stark",
    "exp_month": 1,
    "exp_year": 2030,
    "type": "credit",
    "status": "active",
    "tokenization_status": "pending",
    "created_at": "2026-05-27T10:00:00-03:00",
    "updated_at": "2026-05-27T10:00:00-03:00"
  }
}

Autenticação

Cobranças

Pedidos

Assinaturas

Faturas

Links de Pagamento

Análise de Fraude

Webhooks

Cartões

Visão Geral

Header obrigatório

Formato de resposta padrão

Objeto do cartão

Status de um cartão

Campos de cadastro

Tokenização

Exclusão

Exemplo completo

​Visão Geral

​Header obrigatório

​Formato de resposta padrão

​Objeto do cartão

​Status de um cartão

​Campos de cadastro

​Tokenização

​Exclusão

​Exemplo completo

Visão Geral

Header obrigatório

Formato de resposta padrão

Objeto do cartão

Status de um cartão

Campos de cadastro

Tokenização

Exclusão

Exemplo completo