Skip to main content
POST
Esta rota guarda o cartão de crédito de um cliente no cofre de cartões da Finvia (tokenização: o número do cartão fica com a Finvia e você recebe um identificador para usar no lugar dele). O id devolvido é o que você envia depois como cardTokenId na cobrança com cartão salvo e na assinatura. O seu sistema não precisa guardar o número do cartão. O cartão já nasce active: não há transação de teste, valor para conferir na fatura nem etapa de ativação. O registro também não cobra nada do cliente.

Quando usar

Antes de chamar

  • Tenha uma chave secreta (sk_) válida (Credenciais e ambientes).
  • Tenha o id de um cliente com e-mail e CPF ou CNPJ (Criar cliente). O tipo do documento é deduzido pela quantidade de dígitos de document.id: 11 dígitos é CPF e 14 é CNPJ. Qualquer outro tamanho (passaporte, RG) conta como cliente sem documento, e o registro é recusado.
  • O cartão fica vinculado à conta dona da chave que o registrou. Ele não pode ser usado por outro merchant nem por outra subconta.
O cadastro de cartão não tem modo de teste. Mesmo com a chave de teste (sk_test_), o cartão é registrado de verdade na adquirente, sem nenhuma cobrança. O cofre é o mesmo para teste e produção: um cardTokenId criado na homologação também funciona com a chave de produção, e aí a cobrança é real. Veja como homologar em Cofre de cartões.
Cartão salvo não permite cobrar sem o cliente presente em POST /v1/charges: o CVV do comprador é obrigatório em toda cobrança com cardTokenId. Sem ele, a resposta é 400 com CVV is required when using cardTokenId. Para cobrança automática a cada ciclo, use Assinaturas.

Corpo da requisição

Campos obrigatórios: customerId, number, holderName, expirationMonth, expirationYear e cvv.
string
required
ID do cliente dono do cartão. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q. O cliente precisa ter e-mail e CPF ou CNPJ.
string
required
Número do cartão. Ex.: 4111111111111111.
string
required
Nome impresso no cartão. Ex.: JOAO SILVA.
string
required
Mês de validade, de 01 a 12, com 2 caracteres (minLength 2, maxLength 2). Ex.: 12.
string
required
Ano de validade no formato YYYY, com 4 caracteres (minLength 4, maxLength 4). Ex.: 2028.
string
required
Código de segurança. Mínimo de 3 caracteres. Ex.: 123.
string
Apelido opcional para o cartão. Ex.: Cartão pessoal.
boolean
deprecated
Obsoleto. O campo é aceito, mas não tem efeito: o cartão sempre nasce active, sem transação de teste. Não é preciso enviá-lo.

Respostas

string
ID do token do cartão. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q. É o valor usado como cardTokenId em cobranças e assinaturas e como id nas rotas de cartão.
string
Token do cartão para referência futura. Ex.: tok_abc123xyz.
string | null
Número mascarado do cartão (4 últimos dígitos). Ex.: ****1111. Use para mostrar o cartão ao cliente (“cartão final 1111”).
string
Situação do cartão. Vem sempre active.
boolean
Vem sempre false. O campo continua na resposta por compatibilidade.
Para o negócio: com o cartão no cofre, o cliente não precisa digitar o número de novo nas próximas compras: em cada recompra, ele informa só o CVV. Em assinaturas, o cartão registrado é cobrado automaticamente a cada ciclo. O cartão fica disponível apenas para a conta que o registrou.
Para o desenvolvedor: guarde no seu sistema o id, o maskedNumber e, se quiser, o alias. Nunca guarde number nem cvv. Em evidências de homologação, envie a requisição sem o número completo do cartão. Para saber depois se o cartão ainda pode ser cobrado, use Listar cartões.

Erros comuns

Como testar

O cenário SUB-01 da homologação pede o registro de um cartão para um cliente com e-mail e CPF ou CNPJ, com resultado status: "active" e pendingActivation: false. Na sequência, o SUB-02 usa o cartão registrado em uma cobrança com cardTokenId e cvv. Como o cadastro não tem modo de teste, use um cartão real. Com a chave de teste, a cobrança do SUB-02 é simulada e não movimenta dinheiro.

Veja também

Cofre de cartões

Como funciona o armazenamento e o ciclo de vida do cartão.

Cobrança com cartão salvo

Recompra com cardTokenId e CVV.

Visão geral de assinaturas

Fluxo cards-first: cliente, cartão e assinatura.

Guia de clientes

Requisitos do cliente para ter cartão salvo.