> ## Documentation Index
> Fetch the complete documentation index at: https://docs.z2pay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Listar cartões do cliente
> Lista paginada dos cartões salvos de um cliente, com os dados mascarados que a API guarda.
`GET /customers/{customerId}/cards`
Faz parte do recurso [Cartões](/pt-BR/cards) — como um cartão é salvo e como cobrá-lo depois estão lá.
Retorna uma lista paginada dos cartões daquele cliente, do mais recente para o mais antigo. Não há
filtros: o cliente do caminho já é o recorte.
**A resposta é paginada, e o padrão é 20 por página.** Confira `pagination.totalPages` antes de
concluir que a lista acabou — nada no corpo avisa que houve corte além do próprio `pagination`. O
`limit` aceita até `100`.
**Cliente inexistente responde 404, não lista vazia.** Uma lista vazia significa uma coisa só: o
cliente existe e ainda não tem cartão salvo.
**Cartão desativado some.** Depois do [`DELETE`](/pt-BR/cards/delete) ele sai da listagem e o
`GET` por ID passa a responder `404`. A resposta do próprio `DELETE`, com `status` em `disabled`,
é a última vez que você o vê — se precisa registrar a desativação do seu lado, é dali que ela sai.
**Não existe listagem global de cartões.** Para varrer a conta inteira, percorra os clientes e
liste os cartões de cada um.
## Exemplo
```bash theme={null}
curl -G https://api.sandbox.z2pay.com/v1/customers/cust_j43n74fbt2geb8c1y86ssf6iw/cards \
-H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
--data-urlencode "limit=20"
```
```json theme={null}
{
"data": [
{
"id": "crd_f3r7noniu07ntvbxkcb6sa6x9",
"customerId": "cust_j43n74fbt2geb8c1y86ssf6iw",
"brand": "visa",
"firstDigits": "411111",
"lastDigits": "1111",
"holderName": "JOAO DA SILVA",
"expirationMonth": "12",
"expirationYear": "2030",
"status": "active",
"createdAt": "2026-07-02T19:26:17.000Z",
"updatedAt": "2026-07-02T19:26:17.000Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"totalPages": 1
}
}
```
## OpenAPI
````yaml openapi/psp.json GET /customers/{customerId}/cards
openapi: 3.0.3
info:
title: Z2Pay PSP API
version: 1.0.0
description: API pública do PSP — autenticação via API Key (Credential)
servers:
- url: https://api.sandbox.z2pay.com/v1
description: Sandbox
- url: https://api.z2pay.com/v1
description: Produção
security: []
tags:
- name: Cards
description: Cartões salvos de um cliente
- name: Chargebacks
description: Gerenciamento de chargebacks
- name: Customers
description: Gerenciamento de clientes (compradores)
- name: Fees
description: Tabela de taxas da conta (pix, boleto, cartão, saque, refund, chargeback)
- name: Recipients
description: Gerenciamento de recebedores (sellers/merchants que recebem repasses)
- name: Refunds
description: Gerenciamento de reembolsos e estornos
- name: Splits
description: Regras de divisão do valor de uma venda entre recebedores
- name: Transactions
description: Gerenciamento de transações e payments
- name: Wallets
description: Saldo, extrato e resumo da carteira de um recebedor, agrupados por moeda
- name: Webhooks
description: Configuração, gerenciamento e histórico de entregas de webhooks
- name: Withdrawals
description: Solicitação e acompanhamento de saques (payouts) por recipient
paths:
/customers/{customerId}/cards:
get:
tags:
- Cards
summary: Listar cartões do cliente
description: Retorna a lista paginada de cartões salvos do cliente
operationId: CardController_list
parameters:
- name: page
in: query
required: false
description: 'Página da listagem. Padrão: 1.'
schema:
type: integer
minimum: 1
default: 1
description: 'Página da listagem. Padrão: 1.'
- name: limit
in: query
required: false
description: 'Itens por página. Padrão: 20. Máximo: 100.'
schema:
type: integer
minimum: 1
maximum: 100
default: 20
description: 'Itens por página. Padrão: 20. Máximo: 100.'
- name: customerId
in: path
required: true
description: ID do cliente
schema:
type: string
responses:
'200':
description: Lista paginada de cartões
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
description: ID do cartão (`crd_`).
customerId:
type: string
description: Cliente dono do cartão (`cust_`).
brand:
type: string
description: 'Bandeira (ex.: `visa`, `mastercard`).'
firstDigits:
type: string
description: Seis primeiros dígitos.
lastDigits:
type: string
description: Quatro últimos dígitos.
holderName:
type: string
description: Nome impresso no cartão.
expirationMonth:
type: string
description: Mês de validade (`MM`).
expirationYear:
type: string
description: Ano de validade (`YYYY`).
status:
type: string
description: Situação do cartão.
createdAt:
type: string
description: Criação, ISO 8601.
updatedAt:
type: string
description: Última alteração, ISO 8601.
description: Lista de registros retornados na página atual.
pagination:
type: object
properties:
page:
type: integer
description: Página atual retornada.
limit:
type: integer
description: Quantidade de itens por página.
total:
type: integer
description: Total de itens que atendem ao filtro.
totalPages:
type: integer
description: Total de páginas disponíveis.
description: Dados de paginação do resultado.
example:
data:
- id: crd_hqx4mkpi8dcxbrb2nzynxnjky
customerId: cust_j43n74fbt2geb8c1y86ssf6iw
brand: visa
firstDigits: '411111'
lastDigits: '1111'
holderName: JOAO DA SILVA
expirationMonth: '12'
expirationYear: '2030'
status: active
createdAt: '2026-07-02T19:26:17.000Z'
updatedAt: '2026-07-02T19:26:17.000Z'
pagination:
page: 1
limit: 10
total: 1
totalPages: 1
'400':
description: >-
Requisição inválida — algum parâmetro ou campo do corpo não passou
na validação
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
issues:
type: array
description: >-
Um item por campo rejeitado. Nunca vem vazio: se há
400 de validação, há pelo menos um.
items:
type: object
properties:
path:
type: string
description: >-
Campo que falhou. Vem vazio quando o erro é do
corpo como um todo.
message:
type: string
description: O que há de errado com esse campo.
example:
error:
code: VALIDATION_ERROR
message: Validation failed
issues:
- path: status
message: >-
Status inválido. Valores aceitos: pending,
waiting_payment, paid, refused, canceled, refunded
- path: startDate
message: >-
Data deve ser ISO 8601 com timezone (ex.:
2026-06-24T00:00:00Z)
'401':
description: Chave de API ausente, malformada ou inválida
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: UNAUTHORIZED
message: Invalid API key
'404':
description: Cliente não encontrado
content:
application/json:
schema:
type: object
properties:
error:
type: object
properties:
code:
type: string
description: >-
Identificador estável do erro. É por ele que você deve
ramificar, não pela mensagem.
message:
type: string
description: >-
Descrição legível. Pode mudar sem aviso e não deve ser
usada em condicional.
example:
error:
code: NOT_FOUND
message: Card not found
security:
- apiKey: []
components:
securitySchemes:
apiKey:
type: apiKey
in: header
name: x-api-key
description: API Key da Credential (gerada no Backoffice)
````