> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eximpe.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Saved Cards

> Retrieve a list of saved cards for a specific identifier. Returns tokenized card information without sensitive details.

## 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:**

```bash theme={null}
GET /pg/tokens/?identifier=customer_12345
```

**Response:**

```json theme={null}
{
  "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

```javascript theme={null}
// 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

```python theme={null}
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

1. **Cache Responsibly**: Cache card lists but refresh periodically
2. **Expiry Validation**: Always check if cards are expired before displaying
3. **Error Handling**: Provide clear messaging for empty or error states
4. **Security**: Never log or store the returned card information
5. **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.

## Related Endpoints

* [Save Card](/api-reference/card-tokens/save) - Save new cards for customers
* [Delete Saved Card](/api-reference/card-tokens/delete) - Remove saved cards
* [Create Order](/api-reference/order/create) - Use saved cards in new orders


## OpenAPI

````yaml GET /pg/tokens/
openapi: 3.0.0
info:
  title: Eximpe Payment Gateway API
  description: >-
    API for payment processing and order management through Eximpe payment
    gateway. This specification includes v1, v2, and v3 API versions.
  license:
    name: Proprietary
  version: 2.0.0
servers:
  - url: https://api-pacb-uat.eximpe.com
    description: Payment Gateway Sandbox URL
security:
  - clientAuth: []
    clientSecretAuth: []
    apiVersionHeader: []
tags:
  - name: Card Tokens
  - name: Merchants
  - name: Orders
  - name: Payment Links
  - name: Payments
  - name: Refunds
  - name: Settlements
  - name: Subscriptions
paths:
  /pg/tokens/:
    get:
      tags:
        - Card Tokens
      summary: List Saved Cards
      description: >-
        Retrieve a list of saved cards for a specific identifier. Returns
        tokenized card information without sensitive details.
      operationId: v1_get_pg_tokens_
      parameters:
        - name: identifier
          in: query
          description: Unique identifier to filter saved cards
          required: true
          schema:
            type: string
          example: USER_AS_002
      responses:
        '200':
          description: List of saved cards retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1_ListCardsResponse'
              example:
                success: true
                message: Card details fetched successfully
                data:
                  - card_token: 1e6709282a21e83f43a020
                    identifier: USER_AS_002
                    cardholder_name: ARJUN SINGH
                    nickname: HDFC Millennia Credit Card
                    card_type: credit_card
                    network: visa
                    masked_pan: XXXXXXXXXXXX0003
                    expiry_month: 5
                    expiry_year: 2030
        '401':
          description: Unauthorized - Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1_ErrorResponse'
              example:
                success: false
                error:
                  code: ERR_AUTH_000
                  message: Missing credentials
                  details:
                    authentication: Missing credentials.
      security:
        - clientAuth: []
          clientSecretAuth: []
          merchantAuth: []
          apiVersionHeader: []
components:
  schemas:
    v1_ListCardsResponse:
      type: object
      required:
        - success
        - message
        - data
      properties:
        success:
          type: boolean
          description: Indicates if the request was successful
        message:
          type: string
          description: Response message
        data:
          type: array
          items:
            $ref: '#/components/schemas/v1_SavedCard'
    v1_ErrorResponse:
      type: object
      required:
        - success
        - error
      properties:
        success:
          type: boolean
          enum:
            - false
          description: >-
            Indicates if the request was successful. Always false for error
            responses.
        error:
          $ref: '#/components/schemas/v1_ErrorDetails'
    v1_SavedCard:
      type: object
      required:
        - card_token
        - identifier
        - cardholder_name
        - card_type
        - network
        - masked_pan
        - expiry_month
        - expiry_year
      properties:
        card_token:
          type: string
          description: Unique token for the saved card
        identifier:
          type: string
          description: Unique identifier for the card owner
        cardholder_name:
          type: string
          description: Name on the card
        nickname:
          type: string
          description: Card nickname
        card_type:
          type: string
          description: Type of card
          enum:
            - credit_card
            - debit_card
        network:
          type: string
          description: Card network
          enum:
            - visa
            - mastercard
            - amex
            - discover
            - rupay
        masked_pan:
          type: string
          description: Masked card number for display purposes
          pattern: ^X{8,15}[0-9]{4}$
        expiry_month:
          type: integer
          description: Card expiry month (1-12)
          minimum: 1
          maximum: 12
        expiry_year:
          type: integer
          description: Card expiry year
          minimum: 2024
    v1_ErrorDetails:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Error code (e.g., ERR_ORDER_002)
        message:
          type: string
          description: Error message
        details:
          type: object
          description: Detailed validation error information with field-specific errors
          additionalProperties:
            type: string
            description: Error message for the specific field
  securitySchemes:
    clientAuth:
      type: apiKey
      name: X-Client-ID
      in: header
      description: >-
        **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-displayName: Client ID
      x-example: your-client-id
    clientSecretAuth:
      type: apiKey
      name: X-Client-Secret
      in: header
      description: >-
        **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-displayName: Client Secret
      x-example: your-client-secret
    apiVersionHeader:
      type: apiKey
      name: X-API-Version
      in: header
      description: >-
        **API Version** - Specifies which version of the API to use (e.g.,
        '1.X.X', '2.X.X', or '3.X.X'). This header allows you to control which
        API version your integration uses. Default version information is
        available in the Developer Settings.
      x-displayName: API Version
      x-example: 3.0.0
    merchantAuth:
      type: apiKey
      name: X-Merchant-ID
      in: header
      description: >-
        **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-displayName: Merchant ID
      x-example: your-merchant-id

````