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

# Listar cartões

> Lista os cartões ativos da conta, opcionalmente de um cliente

Lista os cartões ativos da conta (`status: active`, não removidos), do mais recente para o mais antigo. Sem `customer`, traz todos, inclusive os que ainda não têm cliente vinculado.

Permissão: `card.read`. Apenas chave secreta (`sk_…`); chave publicável não lista cartões.

<Note>
  Os exemplos usam o sandbox (`https://api.upag.dev/v1`). Em produção use `https://api.upag.io/v1` com `sk_live_…`.
</Note>

## Endpoint

<CodeGroup>
  ```bash cURL theme={null}
  curl -G https://api.upag.dev/v1/cards \
    -H "Authorization: Bearer sk_test_your_api_key" \
    -d "customer=8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83" \
    -d "page=1" \
    -d "limit=15"
  ```

  ```javascript Node.js SDK theme={null}
  import { Upag } from 'upag';

  const upag = new Upag('sk_test_your_api_key');

  const { data, count } = await upag.cards.list({
    customer: '8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83',
    page: 1,
    limit: 15,
  });
  ```
</CodeGroup>

## Parâmetros

<ParamField query="customer" type="string (uuid)">
  Filtra pelos cartões vinculados a este cliente.
</ParamField>

<ParamField query="page" type="integer" default="1">
  Página, a partir de 1.
</ParamField>

<ParamField query="limit" type="integer" default="15">
  Itens por página, mínimo 1.
</ParamField>

## Resposta

`200 OK`. `count` é o total que corresponde ao filtro.

```json Response theme={null}
{
  "data": [
    {
      "id": "5f0c3d1a-7b2e-4c9d-8a41-0e6f2b9d7c15",
      "customer": "8c1f0a26-5d3b-4f1e-9c72-1a4e6b9d0f83",
      "brand": "visa",
      "firstDigits": "424242",
      "lastDigits": "4242",
      "holderName": "Luke Skywalker",
      "expirationMonth": 11,
      "expirationYear": 2031,
      "funding": "credit",
      "wallet": null,
      "status": "active",
      "createdAt": "2026-07-27T18:04:11.482Z",
      "updatedAt": "2026-07-27T18:06:04.331Z"
    }
  ],
  "count": 1
}
```

Campos em [Referência](./reference).

## Erros

| Status | Causa |
| - | - |
| `403` | Chave publicável (este endpoint exige chave secreta) ou sem a permissão `card.read` |
| `422` | `customer` não é UUID, ou `page`/`limit` inválidos |


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