Para o negócio: o cartão salvo permite a compra com um clique, em que o cliente só confirma o código de segurança, e é a base das assinaturas. O seu sistema guarda só o identificador do cartão e os quatro últimos dígitos para exibição; o número completo fica no cofre da Finvia.
Quando usar
Como funciona
O desenho abaixo mostra o registro do cartão no cofre e os usos do id do cartão salvo.1
Tenha um cliente cadastrado
O cartão é vinculado a um cliente (
customerId), que precisa ter e-mail e CPF ou CNPJ. Veja Clientes.2
Registre o cartão
Envie os dados do cartão para
POST /v1/cards. O cartão é guardado no cofre, já nasce active e a resposta traz o id do cartão salvo.3
Guarde o id e o número mascarado
Grave o
id e o maskedNumber (ex.: ****1111) no seu sistema. Nunca grave o número completo nem o CVV.4
Use o cartão
Em uma cobrança, envie o
id como cardTokenId, com o CVV digitado pelo cliente (Cartão salvo). Em uma assinatura, envie cardTokenId.5
Remova quando necessário
DELETE /v1/cards/{id} revoga o token, que deixa de servir para cobranças e assinaturas.Regras de negócio
O cartão salvo não permite cobrar o cliente ausente fora de uma assinatura: a cobrança avulsa exige o CVV a cada vez. As regras da cobrança estão em Cartão salvo.
Status do cartão
A listagem e a consulta individual mostram status diferentes, porque cada uma lê uma informação diferente.
O desenho abaixo mostra como o status do cartão muda.
pending_validation aparece só em cartões antigos, registrados com o processador anterior.
Passo a passo
1. Registrar o cartão
Resposta
201:
2. Usar o cartão em uma cobrança
Envie oid do cartão como paymentMethod.cardTokenId, com o CVV digitado pelo cliente. Sem o cvv, a resposta é 400 CVV is required when using cardTokenId. O exemplo completo e as regras da cobrança estão em Cartão salvo.
3. Criar uma assinatura com o cartão salvo
4. Listar os cartões do cliente
cURL
customerId, vêm só os cartões não excluídos (active ou expired):
brand, maskedNumber e a validade para montar a lista de cartões na área do cliente (“Visa terminado em 1111, validade 12/2028”).
5. Consultar um cartão
cURL
status segue a tabela de status do cartão: para decidir se o cartão pode ser cobrado, prefira a listagem.
6. Excluir um cartão
cURL
200:
Erros comuns
Perguntas frequentes
O cliente precisa confirmar algum valor na fatura para ativar o cartão?
O cliente precisa confirmar algum valor na fatura para ativar o cartão?
Não. O cartão nasce
active, sem transação de teste e sem etapa de ativação.Posso testar o cofre no sandbox?
Posso testar o cofre no sandbox?
Em parte. O cadastro (
POST /v1/cards) não tem modo de teste: com a chave de teste, o cartão é registrado de verdade, sem cobrar nada. Já a cobrança com cardTokenId em POST /v1/charges é simulada com a chave de teste e não movimenta dinheiro; o resultado segue as regras dos cartões de teste aplicadas ao número guardado. As assinaturas não têm modo de teste: as cobranças delas são reais. Use um cartão real para homologar e lembre que o mesmo cardTokenId funciona com a chave de produção.Um cartão salvo pela conta master pode ser usado por uma subconta?
Um cartão salvo pela conta master pode ser usado por uma subconta?
Não. O cartão pertence ao merchant da chave de API que o registrou e não pode ser usado por outro merchant ou subconta.
Como troco o cartão de uma assinatura?
Como troco o cartão de uma assinatura?
A assinatura não permite troca de cartão. Registre o novo cartão, cancele a assinatura atual e crie outra com o novo
cardTokenId. A nova assinatura começa um ciclo novo, com cobrança imediata.Como testar
Veja também
Cartão salvo
Cobrança com um clique usando o cartão guardado.
Clientes
Cadastro do cliente dono do cartão.
Assinaturas
Cobrança recorrente com cartão salvo.
Registrar cartão
Contrato completo da rota.

