Pular para o conteúdo principal
A API de Cartões expõe os cartões salvos de um customer. Um cartão é criado automaticamente quando você processa uma transação com um token do Tokenizer informando o customerId — você não cria cartões diretamente por esta API.
A Z2Pay nunca armazena nem retorna o número completo do cartão, o CVV ou qualquer dado sensível (PCI). O recurso de cartão guarda apenas dados mascarados: primeiros e últimos dígitos, bandeira, nome do portador e validade. Para tokenizar um cartão use o Tokenizer.
Todas as requisições usam o header x-api-key (veja Autenticação). A base URL de sandbox é https://api.sandbox.z2pay.com.

​
Endpoints

MétodoRotaDescrição
GET/cards/customer/{customerId}Lista os cartões salvos de um customer (paginado)
GET/cards/{id}Busca um cartão por ID
DELETE/cards/{id}Desativa um cartão (soft delete)

​
O objeto Cartão

Estes são os campos retornados em todos os endpoints. Nenhum dado sensível é exposto.
​
id
string
Identificador do cartão, com prefixo crd_.
​
customerId
string
ID do customer dono do cartão (prefixo cust_).
​
brand
string
Bandeira do cartão (ex.: visa, mastercard, elo, amex).
​
firstDigits
string
Primeiros dígitos do cartão (BIN). Não é o número completo.
​
lastDigits
string
Últimos dígitos do cartão. Use junto com brand para exibir o cartão de forma segura (ex.: Visa •••• 4242).
​
holderName
string
Nome do portador, conforme informado na tokenização.
​
expirationMonth
string
Mês de validade, 1 ou 2 dígitos (ex.: 7 ou 07).
​
expirationYear
string
Ano de validade com 4 dígitos (ex.: 2030).
​
status
string
Situação do cartão. Valores possíveis: active, expired, disabled.
​
fingerprint
string
Identificador determinístico do cartão. Cartões iguais (mesmo customer) compartilham o mesmo fingerprint.
​
createdAt
string
Data de criação, em ISO 8601 com timezone.
​
updatedAt
string
Data da última atualização, em ISO 8601 com timezone.
​
deletedAt
string | null
null enquanto o cartão está ativo. Após a desativação, traz a data (ISO 8601) em que o cartão foi desativado.
Valores monetários não se aplicam a este recurso. As datas seguem o padrão ISO 8601 com timezone — veja Convenções.

​
Listar cartões de um customer

GET /cards/customer/{customerId}
Retorna, de forma paginada, os cartões salvos de um customer.

​
Parâmetros de path

​
customerId
string
obrigatório
ID do customer (prefixo cust_).

​
Parâmetros de query

​
page
integer
padrão:"1"
Página a retornar. Inteiro, mínimo 1.
​
limit
integer
padrão:"20"
Quantidade de itens por página. Inteiro, mínimo 1, máximo 100.

​
Exemplo de requisição

curl "https://api.sandbox.z2pay.com/cards/customer/cust_8sdf72kd91?page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Lembre de escapar o & ao montar a URL no shell (use aspas em volta da URL inteira), senão o terminal pode interpretar limit=20 como um comando separado.

​
Exemplo de resposta 200

{
  "data": [
    {
      "id": "crd_4Kp2mZx9Qa",
      "customerId": "cust_8sdf72kd91",
      "brand": "visa",
      "firstDigits": "424242",
      "lastDigits": "4242",
      "holderName": "MARIA DE SOUZA",
      "expirationMonth": "12",
      "expirationYear": "2030",
      "status": "active",
      "fingerprint": "a1b2c3d4e5f6",
      "createdAt": "2026-06-20T14:03:11.000Z",
      "updatedAt": "2026-06-20T14:03:11.000Z",
      "deletedAt": null
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 1,
    "totalPages": 1
  }
}
​
data
array
Lista de objetos Cartão (veja O objeto Cartão).
​
pagination
object
Metadados de paginação: page, limit, total (total de cartões) e totalPages.

​
Buscar cartão por ID

GET /cards/{id}
Retorna os dados de um único cartão.

​
Parâmetros de path

​
id
string
obrigatório
ID do cartão (prefixo crd_).

​
Exemplo de requisição

curl https://api.sandbox.z2pay.com/cards/crd_4Kp2mZx9Qa \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"

​
Exemplo de resposta 200

{
  "id": "crd_4Kp2mZx9Qa",
  "customerId": "cust_8sdf72kd91",
  "brand": "visa",
  "firstDigits": "424242",
  "lastDigits": "4242",
  "holderName": "MARIA DE SOUZA",
  "expirationMonth": "12",
  "expirationYear": "2030",
  "status": "active",
  "fingerprint": "a1b2c3d4e5f6",
  "createdAt": "2026-06-20T14:03:11.000Z",
  "updatedAt": "2026-06-20T14:03:11.000Z",
  "deletedAt": null
}

​
Erros

​
404
Not Found
Cartão não encontrado (ID inexistente ou de outra company). Veja Erros.

​
Desativar cartão

DELETE /cards/{id}
Desativa um cartão salvo. A desativação é um soft delete: o cartão não é apagado, apenas marcado como desativado. A resposta retorna a própria entidade com o campo deletedAt preenchido.
Este endpoint é idempotente. Envie o header Idempotency-Key com um valor único por operação para garantir que reenvios (timeouts, retries) não tenham efeito duplicado. Veja Convenções.

​
Parâmetros de path

​
id
string
obrigatório
ID do cartão a desativar (prefixo crd_).

​
Cabeçalhos

​
Idempotency-Key
string
Chave única da operação. Recomendado para evitar desativações duplicadas em caso de retry.

​
Exemplo de requisição

curl -X DELETE https://api.sandbox.z2pay.com/cards/crd_4Kp2mZx9Qa \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX" \
  -H "Idempotency-Key: 6f1c0b7a-2d3e-4f55-9a11-8c2b7d9e0a31"

​
Exemplo de resposta 200

{
  "id": "crd_4Kp2mZx9Qa",
  "customerId": "cust_8sdf72kd91",
  "brand": "visa",
  "firstDigits": "424242",
  "lastDigits": "4242",
  "holderName": "MARIA DE SOUZA",
  "expirationMonth": "12",
  "expirationYear": "2030",
  "status": "disabled",
  "fingerprint": "a1b2c3d4e5f6",
  "createdAt": "2026-06-20T14:03:11.000Z",
  "updatedAt": "2026-06-24T09:15:42.000Z",
  "deletedAt": "2026-06-24T09:15:42.000Z"
}
Após a desativação, o cartão deixa de aparecer em Listar cartões de um customer.

​
Erros

​
404
Not Found
Cartão não encontrado (ID inexistente ou de outra company). Veja Erros.

​
Veja também

Tokenizer

Como tokenizar dados de cartão de forma segura (PCI) antes de cobrar.

Customers

Gerencie os customers donos dos cartões salvos.

Pagamentos

Cobre usando um token de cartão e o customer.

Cartões de teste

Números de cartão para usar no ambiente de sandbox.