List Saved Cards

Overview

The List Saved Cards endpoint retrieves all saved cards for a specific customer identifier. This endpoint returns only safe, tokenized card information without exposing sensitive details like full card numbers. Use this endpoint to display saved payment methods to customers, allowing them to select from their previously saved cards for faster checkout experiences.

Key Features

🔍 Safe Card Display

Returns masked card numbers (e.g., XXXXXXXXXXXX0003)
Shows only non-sensitive card metadata
No exposure of full card numbers or CVV

🎯 Filtered Results

Filter by customer identifier
Returns only cards belonging to the specified customer
Organized, easy-to-parse card information

💳 Complete Card Context

Card network and type information
Expiry dates for validation
Custom nicknames for easy identification
Cardholder names for verification

Required Parameters

Parameter	Type	Location	Description
`identifier`	string	Query	Unique identifier for the card owner (customer ID, user ID, etc.)

Response Format

The API returns an array of saved card objects, each containing:

Field	Type	Description
`card_token`	string	Unique token for the saved card
`identifier`	string	Customer identifier
`cardholder_name`	string	Name on the card
`nickname`	string	Custom card nickname
`card_type`	string	Card type (credit_card, debit_card)
`network`	string	Card network (visa, mastercard, etc.)
`masked_pan`	string	Masked card number showing only last 4 digits
`expiry_month`	integer	Card expiry month (1-12)
`expiry_year`	integer	Card expiry year

Usage Examples

Basic Card Listing

Request:

GET /pg/tokens/?identifier=customer_12345

Response:

{
  "success": true,
  "message": "Card details fetched successfully",
  "data": [
    {
      "card_token": "1e6709282a21e83f43a020",
      "identifier": "customer_12345",
      "cardholder_name": "John Doe",
      "nickname": "My Business Card",
      "card_type": "credit_card",
      "network": "visa",
      "masked_pan": "XXXXXXXXXXXX1111",
      "expiry_month": 12,
      "expiry_year": 2030
    },
    {
      "card_token": "2f7810393b32f94e54b131",
      "identifier": "customer_12345",
      "cardholder_name": "John Doe",
      "nickname": "Personal Debit",
      "card_type": "debit_card",
      "network": "mastercard",
      "masked_pan": "XXXXXXXXXXXX0008",
      "expiry_month": 8,
      "expiry_year": 2029
    }
  ]
}

Implementation Examples

Frontend Card Display

// Fetch saved cards for a customer
const fetchSavedCards = async (customerId) => {
  try {
    const response = await fetch(`/pg/tokens/?identifier=${customerId}`, {
      headers: {
        'X-Client-ID': 'your_client_id',
        'X-Client-Secret': 'your_client_secret',
        'X-Merchant-ID': 'your_merchant_id'
      }
    });
    
    const data = await response.json();
    return data.data; // Array of saved cards
  } catch (error) {
    console.error('Error fetching saved cards:', error);
    return [];
  }
};

// Display cards in UI
const displaySavedCards = (cards) => {
  return cards.map(card => ({
    token: card.card_token,
    display: `${card.network} **** ${card.masked_pan.slice(-4)}`,
    nickname: card.nickname || `${card.network} ${card.card_type}`,
    expiry: `${card.expiry_month}/${card.expiry_year}`,
    expired: isExpired(card.expiry_month, card.expiry_year)
  }));
};

Backend Integration

import requests

def get_customer_cards(customer_id, client_id, client_secret, merchant_id):
    """Fetch saved cards for a customer"""
    
    headers = {
        'X-Client-ID': client_id,
        'X-Client-Secret': client_secret,
        'X-Merchant-ID': merchant_id,
        'Content-Type': 'application/json'
    }
    
    params = {'identifier': customer_id}
    
    response = requests.get(
        'https://api-pacb.eximpe.com/pg/tokens/',
        headers=headers,
        params=params
    )
    
    if response.status_code == 200:
        return response.json()['data']
    else:
        return []

Security Considerations

🔒 Data Protection

Only masked card numbers are returned
No sensitive data (CVV, full PAN) is exposed
Secure token-based identification

🎯 Access Control

Customer identifier filtering prevents data leakage
Proper authentication required
Cards are only visible to authorized merchants

⏰ Expiry Handling

Check expiry dates before using cards
Implement expiry warnings in your UI
Remove or prompt for updates on expired cards

Error Handling

Status Code	Description	Action
`200`	Success	Process the returned cards
`401`	Unauthorized	Check authentication credentials
`404`	No cards found	Show “no saved cards” message
`500`	Server error	Retry request or show error message

Best Practices

Cache Responsibly: Cache card lists but refresh periodically
Expiry Validation: Always check if cards are expired before displaying
Error Handling: Provide clear messaging for empty or error states
Security: Never log or store the returned card information
UI/UX: Group cards by type or network for better organization

Use Cases

Checkout Flow

Display saved cards during checkout for faster payment processing.

Account Management

Show customers their saved cards in account settings with options to delete.

Payment Method Selection

Allow customers to choose from saved cards or add new ones.

Recurring Payments

Use saved cards for subscription or recurring payment setups.

Save Card - Save new cards for customers
Delete Saved Card - Remove saved cards
Create Order - Use saved cards in new orders

Authorizations

X-Client-ID

string

header

required

Client Application ID - Your unique application identifier used to authenticate API requests. You can find your Client ID in the Developer Settings section of the merchant dashboard.

X-Client-Secret

string

header

required

Client Secret Key - Your secret key used alongside the Client ID for secure authentication. Keep this confidential and never expose it in client-side code. Available in the Developer Settings section of the merchant dashboard.

X-Merchant-ID

string

header

required

Merchant Identifier - The unique ID for the merchant account. This is required for PSP (Payment Service Provider) merchants who manage multiple merchant accounts. You can find merchant IDs in the Merchant Management section of the dashboard.

X-API-Version

string

header

required

API Version - Specifies which version of the API to use (e.g., '1.X.X' or '2.X.X'). This header allows you to control which API version your integration uses. Default version information is available in the Developer Settings.

Query Parameters

identifier

string

required

Unique identifier to filter saved cards

Response

List of saved cards retrieved successfully

success

boolean

required

Indicates if the request was successful

message

string

required

Response message

data

object[]

required

Show child attributes

Order

Payment

Card Tokens

Merchant

Settlement

Refund

Payment Links

Webhooks

Overview

Key Features

🔍 Safe Card Display

🎯 Filtered Results

💳 Complete Card Context

Required Parameters

Response Format

Usage Examples

Basic Card Listing

Implementation Examples

Frontend Card Display

Backend Integration

Security Considerations

🔒 Data Protection

🎯 Access Control

⏰ Expiry Handling

Error Handling

Best Practices

Use Cases

Checkout Flow

Account Management

Payment Method Selection

Recurring Payments

Authorizations

Query Parameters

Response

Order

Payment

Card Tokens

Merchant

Settlement

Refund

Payment Links

Webhooks

​Overview

​Key Features

​🔍 Safe Card Display

​🎯 Filtered Results

​💳 Complete Card Context

​Required Parameters

​Response Format

​Usage Examples

​Basic Card Listing

​Implementation Examples

​Frontend Card Display

​Backend Integration

​Security Considerations

​🔒 Data Protection

​🎯 Access Control

​⏰ Expiry Handling

​Error Handling

​Best Practices

​Use Cases

​Checkout Flow

​Account Management

​Payment Method Selection

​Recurring Payments

​Related Endpoints

Authorizations

Query Parameters

Response

Overview

Key Features

🔍 Safe Card Display

🎯 Filtered Results

💳 Complete Card Context

Required Parameters

Response Format

Usage Examples

Basic Card Listing

Implementation Examples

Frontend Card Display

Backend Integration

Security Considerations

🔒 Data Protection

🎯 Access Control

⏰ Expiry Handling

Error Handling

Best Practices

Use Cases

Checkout Flow

Account Management

Payment Method Selection

Recurring Payments

Related Endpoints