Skip to main content
The Cards API exposes the saved cards of a customer. A card is created automatically when you process a transaction with a token from the Tokenizer by providing the customerId — you do not create cards directly through this API.
Z2Pay never stores or returns the full card number, CVV, or any sensitive data (PCI). The card resource only stores masked data: first and last digits, brand, cardholder name, and expiration date. To tokenize a card, use the Tokenizer.
All requests use the x-api-key header (see Authentication). The sandbox base URL is https://api.sandbox.z2pay.com.

​
Endpoints

MethodRouteDescription
GET/cards/customer/{customerId}Lists saved cards for a customer (paginated)
GET/cards/{id}Retrieves a card by ID
DELETE/cards/{id}Deactivates a card (soft delete)

​
The Card object

These are the fields returned by all endpoints. No sensitive data is exposed.
​
id
string
Card identifier, prefixed with crd_.
​
customerId
string
ID of the customer who owns the card (prefix cust_).
​
brand
string
Card brand (e.g., visa, mastercard, elo, amex).
​
firstDigits
string
First digits of the card (BIN). This is not the full card number.
​
lastDigits
string
Last digits of the card. Use together with brand to display the card safely (e.g., Visa •••• 4242).
​
holderName
string
Cardholder name, as provided during tokenization.
​
expirationMonth
string
Expiration month, 1 or 2 digits (e.g., 7 or 07).
​
expirationYear
string
Expiration year, 4 digits (e.g., 2030).
​
status
string
Card status. Possible values: active, expired, disabled.
​
fingerprint
string
Deterministic card identifier. Identical cards (same customer) share the same fingerprint.
​
createdAt
string
Creation date, in ISO 8601 with timezone.
​
updatedAt
string
Last update date, in ISO 8601 with timezone.
​
deletedAt
string | null
null while the card is active. After deactivation, contains the date (ISO 8601) when the card was deactivated.
Monetary values do not apply to this resource. Dates follow the ISO 8601 standard with timezone — see Conventions.

​
List cards for a customer

GET /cards/customer/{customerId}
Returns the saved cards for a customer in a paginated format.

​
Path parameters

​
customerId
string
required
Customer ID (prefix cust_).

​
Query parameters

​
page
integer
default:"1"
Page to return. Integer, minimum 1.
​
limit
integer
default:"20"
Number of items per page. Integer, minimum 1, maximum 100.

​
Request example

curl "https://api.sandbox.z2pay.com/cards/customer/cust_8sdf72kd91?page=1&limit=20" \
  -H "x-api-key: SUA_CHAVE_DE_SANDBOX"
Remember to escape & when building the URL in the shell (wrap the entire URL in quotes), otherwise the terminal may interpret limit=20 as a separate command.

​
Response example 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
List of Card objects (see The Card object).
​
pagination
object
Pagination metadata: page, limit, total (total number of cards), and totalPages.

​
Retrieve a card by ID

GET /cards/{id}
Returns the data for a single card.

​
Path parameters

​
id
string
required
Card ID (prefix crd_).

​
Request example

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

​
Response example 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
}

​
Errors

​
404
Not Found
Card not found (non-existent ID or ID belonging to another company). See Errors.

​
Deactivate a card

DELETE /cards/{id}
Deactivates a saved card. Deactivation is a soft delete: the card is not deleted, only marked as deactivated. The response returns the entity itself with the deletedAt field populated.
This endpoint is idempotent. Send the Idempotency-Key header with a unique value per operation to ensure that retries (timeouts, retries) have no duplicate effect. See Conventions.

​
Path parameters

​
id
string
required
ID of the card to deactivate (prefix crd_).

​
Headers

​
Idempotency-Key
string
Unique key for the operation. Recommended to prevent duplicate deactivations in case of retry.

​
Request example

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"

​
Response example 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"
}
After deactivation, the card no longer appears in List cards for a customer.

​
Errors

​
404
Not Found
Card not found (non-existent ID or ID belonging to another company). See Errors.

​
See also

Tokenizer

How to tokenize card data securely (PCI) before charging.

Customers

Manage the customers who own the saved cards.

Payments

Charge using a card token and the customer.

Test cards

Card numbers to use in the sandbox environment.