Skip to main content
GET
Esta rota devolve os cartões registrados no cofre da Finvia pela sua conta. Com o filtro customerId, você obtém os cartões de um cliente específico, o que permite montar a tela “meus cartões” no seu site ou mostrar ao cliente, no checkout, o cartão que ele já usou. É também a fonte confiável para saber se um cartão pode ser usado em POST /v1/charges: a cobrança recusa cartão revoked ou expired, e o status desta listagem mostra exatamente essa situação.

Quando usar

Antes de chamar

  • Tenha uma chave secreta (sk_) válida (Credenciais e ambientes).
  • A rota devolve os cartões da conta dona da chave. Cartões registrados por outra conta ou subconta não aparecem.

Parâmetros de consulta

string
Filtra pelo ID do cliente. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q. Com este filtro, vêm só cartões não excluídos (active ou expired). Sem ele, os cartões excluídos (revoked) também aparecem.
Esta listagem não é paginada: a resposta é um array de cartões, sem page, size nem envelope. Ela traz no máximo os 20 cartões mais recentes da conta. Para encontrar o cartão de um cliente específico, use sempre o filtro customerId.

Respostas

A resposta 200 é um array. Cada item tem os campos abaixo.
string
ID do token do cartão. Ex.: 2RhQg9M7ZCg3X3nMb9W1kX8Q. É o valor usado como cardTokenId em cobranças e assinaturas.
string
Token do cartão. Ex.: tok_abc123xyz.
string | null
Número mascarado do cartão. Ex.: ****1111.
string
Bandeira do cartão. Ex.: visa.
string
Mês de validade. Ex.: 12.
string
Ano de validade. Ex.: 2028.
string
Situação do cartão no cofre: active, expired ou revoked. Os valores pending_validation e inactive nunca aparecem nesta listagem.
string
Data e hora de criação (formato date-time). Ex.: 2024-01-15T10:30:00.000Z.
Para o negócio: mostrar ao cliente o cartão salvo (“Visa final 1111, validade 12/2028”) permite oferecer recompra sem digitar o número do cartão de novo. Na cobrança, o cliente ainda informa o CVV. Só cartões com status active podem ser usados.

Erros comuns

Veja também

Cofre de cartões

Como os cartões ficam guardados e quando podem ser usados.

Cobrança com cartão salvo

Usar o cartão listado em uma recompra.

Registrar cartão

Guardar um novo cartão no cofre.

Guia de clientes

O cliente dono do cartão.