> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar cartões

> Devolve os cartões salvos no cofre da sua conta, com filtro opcional por cliente.

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`](https://docs.fastpaybrasil.com/referencia/cobrancas/criar): a cobrança recusa cartão `revoked` ou `expired`, e o `status` desta listagem mostra exatamente essa situação.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Checkout de recompra: mostrar os cartões salvos do cliente | `customerId` com o `id` do cliente |
| Tela "meus cartões" na área logada | `customerId` e exiba `maskedNumber`, `brand` e validade |
| Conferir se um cartão está pronto para cobrança | Verifique se `status` é `active` (prefira esta rota a [Consultar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/consultar.md) para essa decisão) |
| Ver os detalhes de um cartão cujo `id` você já tem | Use [Consultar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/consultar.md) |

## Antes de chamar

* Tenha uma chave secreta (`sk_`) válida ([Credenciais e ambientes](https://docs.fastpaybrasil.com/primeiros-passos/credenciais-e-ambientes.md)).
* 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

**customerId** `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.

> [!NOTE]
>
> 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.

**id** `string`

ID do token do cartão. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`. É o valor usado como `cardTokenId` em cobranças e assinaturas.

**token** `string`

Token do cartão. Ex.: `tok_abc123xyz`.

**maskedNumber** `string | null`

Número mascarado do cartão. Ex.: `****1111`.

**brand** `string`

Bandeira do cartão. Ex.: `visa`.

**expirationMonth** `string`

Mês de validade. Ex.: `12`.

**expirationYear** `string`

Ano de validade. Ex.: `2028`.

**status** `string`

Situação do cartão no cofre: `active`, `expired` ou `revoked`. Os valores `pending_validation` e `inactive` nunca aparecem nesta listagem.

**createdAt** `string`

Data e hora de criação (formato `date-time`). Ex.: `2024-01-15T10:30:00.000Z`.

| `status` | O que significa | Pode ser cobrado? |
| - | - | - |
| `active` | Cartão pronto para uso | Sim |
| `expired` | A validade do cartão passou | Não |
| `revoked` | Cartão excluído com [`DELETE /v1/cards/{id}`](https://docs.fastpaybrasil.com/referencia/cartoes/excluir) | Não |

| HTTP | Significado | Corpo |
| - | - | - |
| `200` | Lista devolvida | Array de cartões |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |

> [!NOTE]
>
> **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

| Sintoma | Causa | Como resolver |
| - | - | - |
| Lista vazia para um cliente que tem cartão | O cartão foi registrado com a chave de outra conta ou subconta | Use a chave da conta que registrou o cartão |
| Cartão antigo não aparece sem filtro | A listagem traz só os 20 cartões mais recentes da conta | Filtre por `customerId` |
| Cartão aparece na lista, mas a cobrança falha | `status` `expired` ou `revoked` | Use só cartões `active` e peça outro cartão ao cliente nos demais casos |
| Código quebra ao ler `meta` ou `data` | A resposta é um array direto | Itere sobre a resposta, sem esperar envelope de paginação |
| `401 Unauthorized` | Chave ausente, inválida ou mal codificada | Codifique em Base64 a chave seguida de `:` |

```http REST (JSON) theme={null}
GET /v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
```

```bash cURL theme={null}
curl -X GET "https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q" \
  -u "$FINVIA_API_KEY:"
```

```javascript Node.js theme={null}
const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const response = await fetch(
  'https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q',
  { headers: { Authorization: `Basic ${credentials}` } },
);

const cards = await response.json(); // array
const usaveis = cards.filter((card) => card.status === 'active');
```

```python Python theme={null}
import os

import requests

response = requests.request(
    "GET",
    "https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'GET',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q"))
            .header("Authorization", "Basic " + credentials)
            .method("GET", HttpRequest.BodyPublishers.noBody())
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

var request = new HttpRequestMessage(HttpMethod.Get, "https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q");

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, err := http.NewRequest("GET", "https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q", nil)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/cards?customerId=2RhQg9M7ZCg3X3nMb9W1kX8Q")
request = Net::HTTP::Get.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```json 200 theme={null}
[
  {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "token": "tok_abc123xyz",
    "maskedNumber": "****1111",
    "brand": "visa",
    "expirationMonth": "12",
    "expirationYear": "2028",
    "status": "active",
    "createdAt": "2024-01-15T10:30:00.000Z"
  }
]
```

```json 401 theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

## Veja também

> [card] [Cofre de cartões](https://docs.fastpaybrasil.com/guias/cofre-de-cartoes.md)
>
> Como os cartões ficam guardados e quando podem ser usados.

> [card] [Cobrança com cartão salvo](https://docs.fastpaybrasil.com/guias/cobrancas/cartao-salvo.md)
>
> Usar o cartão listado em uma recompra.

> [card] [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md)
>
> Guardar um novo cartão no cofre.

> [card] [Guia de clientes](https://docs.fastpaybrasil.com/guias/clientes.md)
>
> O cliente dono do cartão.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.