Skip to main content
Esta página trata do cadastro e da gestão dos cartões: registrar, conferir o status, listar e excluir. A cobrança com um cartão já guardado (compra com um clique) está em Cartão salvo. O cofre de cartões guarda o cartão de crédito do cliente de forma segura e devolve um identificador. Com ele, a sua aplicação deixa de manipular o número do cartão nas próximas compras e pode usar o mesmo cartão em uma assinatura.
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.
O cadastro de cartão não tem modo de teste. Mesmo com a chave de teste (sk_test_), POST /v1/cards registra o cartão de verdade na adquirente. O cadastro não cobra nada: não há transação de validação. O cofre também é o mesmo para teste e produção: um cardTokenId criado na homologação funciona com a chave de produção, e aí a mesma chamada de cobrança é real.

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.
Para saber se um cartão pode ser usado em POST /v1/charges, use a listagem (GET /v1/cards?customerId=...). Hoje a consulta individual pode mostrar active para um cartão já excluído ou vencido. A cobrança recusa cartão revoked ou expired.

Passo a passo

1. Registrar o cartão

Resposta 201:
Para o desenvolvedor: o valor que entra em cardTokenId é o campo id da resposta. A resposta também traz um campo token, que serve só como referência.

2. Usar o cartão em uma cobrança

Envie o id 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

O cartão precisa pertencer ao mesmo merchant da chave de API. Na assinatura, as cobranças de cada ciclo não pedem CVV. Veja Assinaturas.

4. Listar os cartões do cliente

cURL
A resposta é um array, sem paginação, com no máximo os 20 cartões mais recentes. Com o filtro customerId, vêm só os cartões não excluídos (active ou expired):
Use 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
A resposta tem os mesmos campos da listagem. O 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
Resposta 200:
A exclusão revoga o token no cofre. O cartão deixa de servir para cobranças e para assinaturas. Se houver uma assinatura usando esse cartão, as próximas renovações não terão como ser cobradas. Antes de excluir, verifique se o cartão está em uso em alguma assinatura ativa.

Erros comuns

Perguntas frequentes

Não. O cartão nasce active, sem transação de teste e sem etapa de ativação.
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.
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.
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.