List Cards

Retrieve a customer’s enrolled cards. Only non-sensitive card metadata is returned — full PANs (the real card numbers) are never exposed. GET /v1/listCards · Authenticated with your secret key.

Cards are scoped by merchant_id (derived from your secret key) and the customer_id query parameter.

Query parameters

string

required

The customer to list cards for — the same value you passed as user_id when creating the session.

string

default:"active"

active (default) or all (include previously deleted cards for historical reference).

string

default:"false"

true to include card_art_url and display metadata; otherwise those fields are null.

Response

object[]

Show card properties

string

Card id — the same identifier as the SDK enrollmentId from collectPAN().

string

Last 4 digits.

string | null

e.g. "visa", or null if unknown.

number | null

1–12.

number | null

4-digit year.

string | null

Masked PAN, or null.

boolean

Whether this is the customer’s default card.

string

active or deleted.

string | null

Only when include_card_art=true.

object | null

Display metadata (backgroundColor, foregroundColor, labelColor).

string

ISO 8601 enrollment timestamp.

number

Number of cards returned.

Error responses

Status	Code	Cause
400	`INVALID_REQUEST`	Missing `customer_id` query parameter
401	`AUTH_1001`	Invalid API key
401	`AUTH_1002`	Missing or invalid Authorization header
404	`CUSTOMER_NOT_FOUND`	No customer found for the given `customer_id`

curl "https://sandbox.api.prava.space/v1/listCards?customer_id=user_123&status=active" \
  -H "Authorization: Bearer sk_test_..."

import requests

resp = requests.get(
    "https://sandbox.api.prava.space/v1/listCards",
    headers={"Authorization": "Bearer sk_test_..."},
    params={"customer_id": "user_123", "status": "active"},
)

const resp = await fetch(
  "https://sandbox.api.prava.space/v1/listCards?customer_id=user_123&status=active",
  {
    headers: {
      Authorization: "Bearer sk_test_...",
    },
  }
);

{
  "cards": [
    {
      "card_id": "card_1",
      "card_last4": "4242",
      "card_brand": "visa",
      "card_exp_month": 12,
      "card_exp_year": 2030,
      "is_default": true,
      "status": "active",
      "created_at": "2026-05-01T10:00:00Z"
    }
  ],
  "count": 1
}

{
  "error": { "code": "INVALID_REQUEST", "message": "Missing customer_id" }
}

{
  "error": { "code": "CUSTOMER_NOT_FOUND", "message": "No customer for the given customer_id" }
}

Server-Side API

Reference

Query parameters

Response

Error responses

​Query parameters

​Response

​Error responses

Query parameters

Response

Error responses