> ## 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.

# Save Card

> Save card details securely for future transactions. The card information is tokenized and stored securely.

## Overview

The Save Card endpoint allows you to securely save card details for future transactions. Card information is tokenized and stored securely, ensuring PCI compliance while enabling seamless repeat transactions.

When you save a card, the system generates a unique `card_token` that can be used for future payments without requiring the customer to re-enter their card details.

## Key Features

### 🔒 **Security First**

* Card numbers are immediately tokenized and never stored in plain text
* PCI DSS compliant tokenization process
* Secure token-based card management

### 📱 **Customer Consent**

* Explicit cardholder consent verification required
* Compliance with data protection regulations

### 🏷️ **Card Organization**

* Optional card nickname for easy identification
* Support for multiple card types (Credit Card, Debit Dard)
* Network identification (VISA, MASTERCARD, AMEX, etc.)

## Required Parameters

| Parameter         | Type    | Description                                                       |
| ----------------- | ------- | ----------------------------------------------------------------- |
| `identifier`      | string  | Unique identifier for the card owner (customer ID, user ID, etc.) |
| `card_number`     | string  | Full card number (will be tokenized immediately)                  |
| `cardholder_name` | string  | Name as it appears on the card                                    |
| `expiry_month`    | integer | Card expiry month (1-12)                                          |
| `expiry_year`     | integer | Card expiry year (YYYY format)                                    |
| `network`         | string  | Card network (visa, mastercard, amex, discover, rupay)            |
| `card_type`       | string  | Type of card (credit\_card, debit\_card)                          |
| `nickname`        | string  | Custom name for easy card identification                          |

## Conditional Parameters

| Parameter                        | Type   | Description                                                    |
| -------------------------------- | ------ | -------------------------------------------------------------- |
| `authorization_reference_number` | string | **Required for Rupay and AMEX cards only** - See details below |

### Authorization Reference Number Details

The `authorization_reference_number` parameter is **mandatory** for specific card networks:

#### **Rupay Cards**

* **Required**: Yes
* **Value**: The authorization reference number received during the authorization call of Rupay card transactions
* **Note**: Authentication reference number will be sent by the PG in the authorization response. Currently, this check is skipped by Rupay

#### **AMEX Cards**

* **Required**: Yes
* **Value**: The AEVV (American Express Verification Value) received during authorization call of AMEX card transactions
* **Note**: American Express Verification Value will be sent by the PG in the authorization response

#### **Other Networks (VISA, MASTERCARD, DISCOVER)**

* **Required**: No
* **Value**: This parameter should not be included for other card networks

## Response

The API returns a tokenized representation of the saved card:

* `card_label`: Display-friendly card label
* `card_token`: Unique token for future transactions

## Usage Examples

### Saving a Credit Card

```json theme={null}
{
  "identifier": "customer_12345",
  "card_number": "4111111111111111",
  "nickname": "My VISA Card",
  "cardholder_name": "John Doe",
  "expiry_month": 12,
  "expiry_year": 2030,
  "network": "visa",
  "card_type": "credit_card"
}
```

### Saving a Debit Card

```json theme={null}
{
  "identifier": "customer_67890",
  "card_number": "5506900480000008",
  "nickname": "Business Debit",
  "cardholder_name": "Jane Smith",
  "expiry_month": 8,
  "expiry_year": 2029,
  "network": "mastercard",
  "card_type": "debit_card"
}
```

### Saving a Rupay Card (with Authorization Reference)

```json theme={null}
{
  "identifier": "customer_98765",
  "card_number": "6521123456789012",
  "nickname": "Rupay Debit",
  "cardholder_name": "Raj Patel",
  "expiry_month": 6,
  "expiry_year": 2031,
  "network": "rupay",
  "card_type": "debit_card",
  "authorization_reference_number": "AUTH_REF_789012345"
}
```

### Saving an AMEX Card (with AEVV)

```json theme={null}
{
  "identifier": "customer_54321",
  "card_number": "378282246310005",
  "nickname": "AMEX Business",
  "cardholder_name": "Sarah Johnson",
  "expiry_month": 10,
  "expiry_year": 2032,
  "network": "amex",
  "card_type": "credit_card",
  "authorization_reference_number": "AEVV_ABC123DEF456"
}
```

## Security Notes

* **Immediate Tokenization**: Card numbers are tokenized as soon as they're received
* **No Plain Text Storage**: Full card numbers are never stored in our systems
* **Token Uniqueness**: Each saved card gets a unique, non-reversible token

## Error Handling

### Common Error Responses

#### 400 - Validation Error

When required fields are missing or invalid:

```json theme={null}
{
  "success": false,
  "error": {
    "type": "validation_error",
    "errors": [
      {
        "code": "invalid",
        "detail": "This field is required.",
        "attr": "card_number"
      }
    ]
  }
}
```

#### Multiple Validation Errors

```json theme={null}
{
  "success": false,
  "error": {
    "type": "validation_error",
    "errors": [
      {
        "code": "invalid",
        "detail": "This field is required.",
        "attr": "cardholder_name"
      },
      {
        "code": "invalid",
        "detail": "Invalid card number format.",
        "attr": "card_number"
      },
      {
        "code": "invalid",
        "detail": "Authorization reference number is required for Rupay cards.",
        "attr": "authorization_reference_number"
      }
    ]
  }
}
```

#### Authorization Reference Number Missing (Rupay/AMEX)

```json theme={null}
{
  "success": false,
  "error": {
    "type": "validation_error",
    "errors": [
      {
        "code": "invalid",
        "detail": "Authorization reference number is required for Rupay cards.",
        "attr": "authorization_reference_number"
      }
    ]
  }
}
```

#### 401 - Authentication Error

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERR_AUTH_000",
    "message": "Missing credentials",
    "details": {
      "authentication": "Missing credentials."
    }
  }
}
```

### Error Response Structure

| Status Code | Error Type           | Description                                 |
| ----------- | -------------------- | ------------------------------------------- |
| `400`       | Validation Error     | Missing or invalid request parameters       |
| `401`       | Authentication Error | Invalid or missing credentials              |
| `403`       | Authorization Error  | Insufficient permissions                    |
| `409`       | Conflict Error       | Card already exists or duplicate identifier |
| `500`       | Server Error         | Internal system error                       |

## Best Practices

1. **Always Verify Consent**: Ensure customers explicitly consent before saving cards
2. **Use Descriptive Nicknames**: Help customers identify their cards easily
3. **Validate Card Details**: Verify card information before saving
4. **Handle Errors Gracefully**: Implement proper error handling for failed saves
5. **Secure Transmission**: Always use HTTPS for card data transmission

## Next Steps

After saving a card successfully:

1. Store the returned `card_token` securely
2. Use the token for future order creation
3. Allow customers to manage their saved cards
4. Implement card deletion when customers request it

## Related Endpoints

* [List Saved Cards](/api-reference/v1/card-tokens/list) - Retrieve saved cards for a customer
* [Delete Saved Card](/api-reference/v1/card-tokens/delete) - Remove a saved card
* [Create Order](/api-reference/v1/order/create) - Use saved cards in orders


## OpenAPI

````yaml POST /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/:
    post:
      tags:
        - Card Tokens
      summary: Save Card
      description: >-
        Save card details securely for future transactions. The card information
        is tokenized and stored securely.
      operationId: v1_post_pg_tokens_
      requestBody:
        description: Card details to save
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/v1_SaveCardRequest'
            examples:
              MasterCard Example:
                summary: Saving a MasterCard
                value:
                  identifier: USER_PS_001
                  card_number: '5506900480000008'
                  nickname: HDFC Regalia Credit Card
                  cardholder_name: Priya Sharma
                  expiry_month: 5
                  expiry_year: 2030
                  network: mastercard
                  card_type: credit_card
              Rupay Card Example:
                summary: Saving a Rupay card (requires authorization_reference_number)
                value:
                  identifier: USER_RP_002
                  card_number: '6521123456789012'
                  nickname: SBI RuPay Platinum Debit
                  cardholder_name: Rajesh Patel
                  expiry_month: 6
                  expiry_year: 2031
                  network: rupay
                  card_type: debit_card
                  authorization_reference_number: AUTH_REF_SBI_789012345
              AMEX Card Example:
                summary: >-
                  Saving an AMEX card (requires authorization_reference_number
                  with AEVV)
                value:
                  identifier: USER_SJ_003
                  card_number: '378282246310005'
                  nickname: AMEX Gold Business Card
                  cardholder_name: Sanjana Joshi
                  expiry_month: 10
                  expiry_year: 2032
                  network: amex
                  card_type: credit_card
                  authorization_reference_number: AEVV_AMEX_ABC123DEF456
      responses:
        '200':
          description: Card saved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1_SaveCardResponse'
              example:
                success: true
                message: Card details saved successfully
                data:
                  card_label: HDFC Regalia Credit Card
                  card_token: c8a28bca2021ead49124
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/v1_ErrorResponse'
              examples:
                Missing Required Field:
                  summary: Required field missing
                  value:
                    success: false
                    error:
                      type: validation_error
                      errors:
                        - code: invalid
                          detail: This field is required.
                          attr: card_number
                Multiple Validation Errors:
                  summary: Multiple field validation errors
                  value:
                    success: false
                    error:
                      type: validation_error
                      errors:
                        - code: invalid
                          detail: This field is required.
                          attr: cardholder_name
                        - code: invalid
                          detail: Invalid card number format.
                          attr: card_number
        '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_SaveCardRequest:
      type: object
      required:
        - identifier
        - card_number
        - cardholder_name
        - expiry_month
        - expiry_year
        - network
        - card_type
      properties:
        identifier:
          type: string
          description: Unique identifier for the card owner
        card_number:
          type: string
          description: Card number (will be tokenized and securely stored)
          pattern: ^[0-9]{13,19}$
        nickname:
          type: string
          description: Card nickname for easy identification
        cardholder_name:
          type: string
          description: Name on the card
        expiry_month:
          type: integer
          description: Card expiry month (1-12)
          minimum: 1
          maximum: 12
        expiry_year:
          type: integer
          description: Card expiry year (YYYY format)
          minimum: 2024
        network:
          type: string
          description: Card network
          enum:
            - visa
            - mastercard
            - amex
            - discover
            - rupay
        card_type:
          type: string
          description: Type of card
          enum:
            - credit_card
            - debit_card
        authorization_reference_number:
          type: string
          description: >-
            Conditional parameter required for specific card networks: For Rupay
            cards - the authorization reference number received during
            authorization call. For AMEX cards - the AEVV (American Express
            Verification Value) received during authorization call. This
            parameter is mandatory for Rupay and AMEX cards only.
    v1_SaveCardResponse:
      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: object
          required:
            - card_label
            - card_token
          properties:
            card_label:
              type: string
              description: Display label for the saved card
            card_token:
              type: string
              description: Unique token for the saved card
    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_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

````