Endpoint
| Environment | Full URL |
|---|
| Sandbox | https://sandbox.api.prava.space/v1/listCards |
| Production | https://api.prava.space/v1/listCards |
Authentication
Bearer token using your secret key:
Authorization: Bearer sk_test_xxx
merchant_id (derived from your secret key) and the customer_id query parameter.
Query Parameters
Required
The customer ID to retrieve cards for (the user_id used when creating the session)
Optional
Filter by card status: active (default) or all (includes deleted cards)
Include card art URL in response: "true" or "false" (default: "false")
Response (200)
Array of card objects
Unique card identifier (the same as the enrollmentId from the SDK’s collectPAN())
Last 4 digits of the card number
Card brand (e.g., "visa"), or null if unknown
Expiration year (4 digits)
Masked card number (e.g., "•••• •••• •••• 4242"), or null
Whether this is the customer’s default card
Card status — active or deleted
Card art image URL (only present when include_card_art=true)
Card display metadata (brand colors: backgroundColor, foregroundColor, labelColor)
ISO 8601 timestamp of when the card was enrolled
Total number of cards returned
Example
Swap the host for production: use https://api.prava.space instead of https://sandbox.api.prava.space.
curl "https://sandbox.api.prava.space/v1/listCards?customer_id=user_123&status=active" \
-H "Authorization: Bearer sk_test_xxx"
curl "https://api.prava.space/v1/listCards?customer_id=user_123&status=active" \
-H "Authorization: Bearer sk_live_xxx"
const BASE_URL = 'https://sandbox.api.prava.space'; // or https://api.prava.space
const result = await fetch(
`${BASE_URL}/v1/listCards?customer_id=user_123&status=active`,
{
headers: {
'Authorization': `Bearer ${SECRET_KEY}`,
},
}
).then(res => res.json());
console.log(result.cards); // Array of card objects
console.log(result.count); // Number of cards
Response
{
"cards": [
{
"card_id": "enr_abc123",
"card_last4": "4242",
"card_brand": "visa",
"card_exp_month": 12,
"card_exp_year": 2027,
"masked_card_number": "•••• •••• •••• 4242",
"is_default": true,
"status": "active",
"card_art_url": null,
"metadata": {
"backgroundColor": "#1A1F71",
"foregroundColor": "#FFFFFF",
"labelColor": "#CCCCCC"
},
"created_at": "2026-03-15T10:30:00Z"
}
],
"count": 1
}
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 |
{
"error": {
"code": "AUTH_1001",
"message": "Invalid API key"
}
}
Notes
- Only non-sensitive card metadata is returned — full PANs are never exposed.
- Use
status=all to include previously deleted cards for historical reference.
- The
card_id returned here is the same as the enrollmentId from the SDK’s collectPAN().
