Saltar al contenido principal
La API de Tarjetas expone las tarjetas guardadas de un customer. Una tarjeta se crea automáticamente cuando procesas una transacción con un token del Tokenizer indicando el customerId — no se crean tarjetas directamente a través de esta API.
Z2Pay nunca almacena ni devuelve el número completo de la tarjeta, el CVV ni ningún dato sensible (PCI). El recurso de tarjeta guarda únicamente datos enmascarados: primeros y últimos dígitos, marca, nombre del titular y vencimiento. Para tokenizar una tarjeta utiliza el Tokenizer.
Todas las solicitudes utilizan el header x-api-key (consulta Autenticación). La URL base de sandbox es https://api.sandbox.z2pay.com.

​
Endpoints

MétodoRutaDescripción
GET/cards/customer/{customerId}Lista las tarjetas guardadas de un customer (paginado)
GET/cards/{id}Obtiene una tarjeta por ID
DELETE/cards/{id}Desactiva una tarjeta (soft delete)

​
El objeto Tarjeta

Estos son los campos devueltos en todos los endpoints. No se expone ningún dato sensible.
​
id
string
Identificador de la tarjeta, con prefijo crd_.
​
customerId
string
ID del customer propietario de la tarjeta (prefijo cust_).
​
brand
string
Marca de la tarjeta (ej.: visa, mastercard, elo, amex).
​
firstDigits
string
Primeros dígitos de la tarjeta (BIN). No es el número completo.
​
lastDigits
string
Últimos dígitos de la tarjeta. Úsalos junto con brand para mostrar la tarjeta de forma segura (ej.: Visa •••• 4242).
​
holderName
string
Nombre del titular, tal como se informó en la tokenización.
​
expirationMonth
string
Mes de vencimiento, con 1 o 2 dígitos (ej.: 7 o 07).
​
expirationYear
string
Año de vencimiento con 4 dígitos (ej.: 2030).
​
status
string
Estado de la tarjeta. Valores posibles: active, expired, disabled.
​
fingerprint
string
Identificador determinístico de la tarjeta. Tarjetas iguales (del mismo customer) comparten el mismo fingerprint.
​
createdAt
string
Fecha de creación, en ISO 8601 con timezone.
​
updatedAt
string
Fecha de la última actualización, en ISO 8601 con timezone.
​
deletedAt
string | null
null mientras la tarjeta está activa. Tras la desactivación, contiene la fecha (ISO 8601) en que la tarjeta fue desactivada.
Los valores monetarios no aplican a este recurso. Las fechas siguen el estándar ISO 8601 con timezone — consulta Convenciones.

​
Listar tarjetas de un customer

GET /cards/customer/{customerId}
Devuelve, de forma paginada, las tarjetas guardadas de un customer.

​
Parámetros de path

​
customerId
string
requerido
ID del customer (prefijo cust_).

​
Parámetros de query

​
page
integer
predeterminado:"1"
Página a devolver. Entero, mínimo 1.
​
limit
integer
predeterminado:"20"
Cantidad de elementos por página. Entero, mínimo 1, máximo 100.

​
Ejemplo de solicitud

curl "https://api.sandbox.z2pay.com/cards/customer/cust_8sdf72kd91?page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Recuerda escapar el & al construir la URL en el shell (usa comillas alrededor de la URL completa), de lo contrario el terminal puede interpretar limit=20 como un comando separado.

​
Ejemplo de respuesta 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 Tarjeta (consulta El objeto Tarjeta).
​
pagination
object
Metadatos de paginación: page, limit, total (total de tarjetas) y totalPages.

​
Obtener tarjeta por ID

GET /cards/{id}
Devuelve los datos de una única tarjeta.

​
Parámetros de path

​
id
string
requerido
ID de la tarjeta (prefijo crd_).

​
Ejemplo de solicitud

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

​
Ejemplo de respuesta 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
}

​
Errores

​
404
Not Found
Tarjeta no encontrada (ID inexistente o de otra company). Consulta Errores.

​
Desactivar tarjeta

DELETE /cards/{id}
Desactiva una tarjeta guardada. La desactivación es un soft delete: la tarjeta no se elimina, solo se marca como desactivada. La respuesta devuelve la propia entidad con el campo deletedAt completado.
Este endpoint es idempotente. Envía el header Idempotency-Key con un valor único por operación para garantizar que los reenvíos (timeouts, retries) no tengan efecto duplicado. Consulta Convenciones.

​
Parámetros de path

​
id
string
requerido
ID de la tarjeta a desactivar (prefijo crd_).

​
Cabeceras

​
Idempotency-Key
string
Clave única de la operación. Recomendado para evitar desactivaciones duplicadas en caso de retry.

​
Ejemplo de solicitud

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"

​
Ejemplo de respuesta 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"
}
Tras la desactivación, la tarjeta deja de aparecer en Listar tarjetas de un customer.

​
Errores

​
404
Not Found
Tarjeta no encontrada (ID inexistente o de otra company). Consulta Errores.

​
Ver también

Tokenizer

Cómo tokenizar datos de tarjeta de forma segura (PCI) antes de cobrar.

Customers

Gestiona los customers propietarios de las tarjetas guardadas.

Pagos

Cobra utilizando un token de tarjeta y el customer.

Tarjetas de prueba

Números de tarjeta para usar en el entorno de sandbox.