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

# Cards

> Issue, manage, lock, and cancel corporate cards.

<Tabs>
  <Tab title="v3">
    <Note>Recommended for all new integrations.</Note>

    Clara's Cards API lets you manage **physical and virtual cards** for your users and teams. You can create cards, retrieve details, update names, change statuses, and more — all programmatically.

    | Operation                          | Endpoint                              | Method |
    | ---------------------------------- | ------------------------------------- | ------ |
    | Find all cards                     | `/api/v3/cards`                       | GET    |
    | Find card by UUID                  | `/api/v3/cards/{uuid}`                | GET    |
    | Find all card requests by batch ID | `/api/v3/cards/requests/batches/{id}` | GET    |
    | Find all card requests by ID       | `/api/v3/cards/requests/{id}`         | GET    |
    | Find all card requests             | `/api/v3/cards/requests`              | GET    |
    | Create cards                       | `/api/v3/cards/bulk-create`           | POST   |
    | Single create card                 | `/api/v3/cards`                       | POST   |
    | Update single card threshold       | `/api/v3/cards/{uuid}/threshold`      | PATCH  |
    | Update multiple cards threshold    | `/api/v3/cards/threshold`             | PATCH  |
    | Lock/unlock a single card          | `/api/v3/cards/{uuid}/lock`           | PATCH  |
    | Lock/unlock multiple cards         | `/api/v3/cards/lock`                  | PATCH  |
    | Delete card                        | `/api/v3/cards/{uuid}`                | DELETE |
    | Delete cards                       | `/api/v3/cards/delete`                | POST   |

    <br />

    ## Find All Cards

    List **all cards** in your account.

    ### Endpoint

    `GET /api/v3/cards`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X GET "https://public-api.mx.clara.com/api/v3/cards/" \
    --cert /path/to/client-cert.pem \
    --key /path/to/client-key.pem \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    ### Sample JSON Response

    ```json JSON theme={null}
    {
      "content": [
        {
          "uuid": "dd9bf99c-648b-419d-8316-32201ef91289",
          "claraStatus": "ACTIVE",
          "status": "ACTIVE",
          "lockCode": "UNLOCKED",
          "alias": "Marketing Card",
          "threshold": 1000.0,
          "periodicity": "MONTHLY",
          "maskedPan": "510979******9579",
          "type": "MASTER_VIRTUAL",
          "user": {
            "uuid": "c3fb1f07-5e7f-47b8-9819-0b09151b8099",
            "fullName": "Ana García",
            "username": "ana.garcia@company.com"
          }
        }
      ],
      "totalElements": 379,
      "totalPages": 190,
      "size": 2,
      "number": 0
    }
    ```

    ### Query Parameters

    | **Parameter** | **Type**  | **Description**                                                               | **Valid Values / Notes**                                        |
    | ------------- | --------- | ----------------------------------------------------------------------------- | --------------------------------------------------------------- |
    | `page`        | `integer` | Zero-based index of the page to retrieve. Used for pagination.                | `0..N`                                                          |
    | `size`        | `integer` | Number of records to retrieve per page.                                       | Max allowed may depend on backend constraints                   |
    | `userUuid`    | `string`  | Filter cards that belong to a specific user by UUID.                          | Cannot be used in combination with `userErpId`                  |
    | `username`    | `string`  | Filter cards by the associated user's username (email/handle).                | Must be exact match                                             |
    | `status`      | `string`  | Filter by card status.                                                        | e.g., `ACTIVE`, `BLOCKED`, `CANCELLED`, `EXPIRED`, etc.         |
    | `periodicity` | `string`  | Filter cards by their spending limit periodicity.                             | `DAILY`, `WEEKLY`, `MONTHLY`                                    |
    | `type`        | `string`  | Filter by the card's product and format type.                                 | See full list below                                             |
    | `userErpId`   | `string`  | ERP-specific user identifier. Applies only if `userUuid` is **not** provided. | Used for integrations with ERP systems like SAP, NetSuite, etc. |

    ✅ Valid Values for type

    | **Value**            | **Description**                               |
    | -------------------- | --------------------------------------------- |
    | `MASTER_WORLD_ELITE` | Mastercard-branded premium "World Elite" card |
    | `MASTER_CORPORATE`   | Mastercard corporate-level card               |
    | `MASTER_VIRTUAL`     | Virtual Mastercard                            |
    | `VISA_PHYSICAL`      | Physical Visa card                            |
    | `VISA_VIRTUAL`       | Virtual Visa card                             |

    ⚠️ This field represents a combination of network + format + product line (not just "VIRTUAL" / "PHYSICAL" like in the POST endpoint).

    ## Find Card by UUID

    Fetch a **single card** by its UUID.

    ### Endpoint

    `GET /api/v3/cards/{uuid}`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X GET "https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e" \
    --cert /path/to/client-cert.pem \
    --key /path/to/client-key.pem \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    ### Sample JSON Response

    ```json JSON theme={null}
    {
      "uuid": "dd9bf99c-648b-419d-8316-32201ef91289",
      "claraStatus": "ACTIVE",
      "status": "ACTIVE",
      "lockCode": "UNLOCKED",
      "alias": "Marketing Card",
      "threshold": 1000.0,
      "periodicity": "MONTHLY",
      "maskedPan": "510979******9579",
      "type": "MASTER_VIRTUAL",
      "cvv": "705",
      "expiryDate": "12/30",
      "numberOnCard": "5109790205009579",
      "user": {
        "uuid": "c3fb1f07-5e7f-47b8-9819-0b09151b8099",
        "fullName": "Ana García",
        "username": "ana.garcia@company.com"
      }
    }
    ```

    <br />

    ## Create Cards (Bulk)

    Create multiple cards asynchronously.

    ### Endpoint

    `POST /api/v3/cards/bulk-create`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X POST "https://public-api.mx.clara.com/api/v3/cards/bulk-create" \
    --cert /path/to/client-cert.pem \
    --key /path/to/client-key.pem \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "cardsRequests": [
        {
          "type": "virtual",
          "alias": "Ops Team",
          "userUUID": "user-uuid-1",
          "threshold": 500,
          "periodicityType": "DAILY"
        }
      ]
    }'
    ```

    🕑 Cards are created async—monitor via webhook or poll /v3/cards.

    <br />

    ## Create Single Card

    Create one card directly.

    ### Endpoint

    `POST /api/v3/cards`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X POST "https://public-api.mx.clara.com/api/v3/cards" \
    --cert /path/to/client-cert.pem \
    --key /path/to/client-key.pem \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "type": "physical",
      "alias": "Team Card",
      "userUUID": "user-uuid-2",
      "threshold": 1000,
      "periodicityType": "MONTHLY"
    }'
    ```

    ### Request Body Fields

    | **Field**      | **Type** | **Required** | **Description**                                 | **Valid Values / Notes**                                     |
    | -------------- | -------- | ------------ | ----------------------------------------------- | ------------------------------------------------------------ |
    | `type`         | `string` | ✅ Yes        | Defines whether the card is virtual or physical | `VIRTUAL`, `PHYSICAL`                                        |
    | `alias`        | `string` | ✅ Yes        | Alias or nickname to identify the card          | Free-text                                                    |
    | `userUuid`     | `uuid`   | ✅ Yes        | UUID of the cardholder                          | Must belong to a valid user in your organization             |
    | `threshold`    | `number` | ❌ No         | Spending limit assigned to the card             | Must respect credit policies and cannot exceed company limit |
    | `businessType` | `string` | ❌ No         | Defines the business product tier of the card   | `BUSINESS`, `WORLD_ELITE`                                    |
    | `periodicity`  | `string` | ❌ No         | Frequency at which the threshold resets         | `DAILY`, `WEEKLY`, `MONTHLY`                                 |

    ## Update Card Threshold

    Adjust the spending limit for a card.

    ### Endpoint

    `PATCH /api/v3/cards/{uuid}/threshold`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X PATCH "https://public-api.mx.clara.com/api/v3/cards/abc-123/threshold" \
    --cert /path/to/client-cert.pem \
    --key /path/to/client-key.pem \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"threshold": 800}'
    ```

    <br />

    ## Toggle Card Lock

    Lock or unlock a card.

    ### Endpoint

    `PATCH /api/v3/cards/{uuid}/lock`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X PATCH "https://public-api.mx.clara.com/api/v3/cards/abc-123/lock" \
    --cert /path/to/client-cert.pem \
    --key /path/to/client-key.pem \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{"locked": true, "lockCode": 16}'
    ```

    ### Request Body

    | Field      | Type    | Required | Description                          |
    | ---------- | ------- | -------- | ------------------------------------ |
    | `locked`   | boolean | ✅        | `true` to lock, `false` to unlock    |
    | `lockCode` | integer | ✅        | Must be `16` for API-initiated locks |

    ### Response (202 Accepted — async)

    ```json theme={null}
    {
      "batchId": "836ce8d6-e767-4a3f-827c-14919413638c",
      "id": "8034e101-adc9-4a65-8cfc-ddd98c4377e0",
      "uuid": "dd9bf99c-648b-419d-8316-32201ef91289",
      "status": "UPDATED"
    }
    ```

    ### lockCode values

    The `lockCode` field identifies who is initiating the lock. Use `16` for API-initiated locks.

    | `lockCode` | Initiated by      | Description                                                                      |
    | ---------- | ----------------- | -------------------------------------------------------------------------------- |
    | `16`       | API / integration | Standard user-initiated lock. Use this for programmatic lock/unlock via the API. |

    Locks can also be applied by manager hierarchy (Master Lock) or by Clara's internal team (Clara Blocked). These originate from different sources and cannot be set via the API — they are reflected in the `lockCode` field when you read the card back with `GET /api/v3/cards/{uuid}`.

    <br />

    ## Delete a Card

    Cancel (soft-delete) a single card.

    ### Endpoint

    `DELETE /api/v3/cards/{uuid}`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X DELETE "https://public-api.mx.clara.com/api/v3/cards/abc-123" \
    --cert /path/to/client-cert.pem \
    --key /path/to/client-key.pem \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    <br />

    ## Delete Multiple Cards

    Cancel multiple cards in one request.

    ### Endpoint

    `POST /api/v3/cards/delete`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X POST "https://public-api.mx.clara.com/api/v3/cards/delete" \
    --cert /path/to/client-cert.pem \
    --key /path/to/client-key.pem \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "uuids": ["abc-123", "def-456"]
    }'
    ```

    <br />

    ⚠️ **Important Notes:**

    * Threshold changes and locks are allowed only on active cards.
    * Locking a card prevents usage; unlocking restores access.
    * Deleted cards cannot be recovered.
    * Ensure your threshold doesn't exceed your company's credit limit.

    💡 **Tip:** Use locking to disable lost/stolen cards and delete to permanently remove unused ones.

    ***

    ## Endpoint Reference

    ### `GET /api/v3/cards`

    List all cards (v3)

    **Parameters:**

    | Parameter     | In    | Type          | Required | Description                                          |
    | ------------- | ----- | ------------- | -------- | ---------------------------------------------------- |
    | `userUuid`    | query | string (uuid) |          | Filter by user UUID                                  |
    | `username`    | query | string        |          | Filter by username                                   |
    | `status`      | query | string        |          | Filter by card status                                |
    | `periodicity` | query | string        |          | Filter by periodicity                                |
    | `type`        | query | string        |          | Filter by card type                                  |
    | `userErpId`   | query | string        |          | Filter by user ERP ID (only if userUuid not present) |
    | `claraStatus` | query | string        |          | \[DEPRECATED] Use 'status' instead                   |

    **Response Schema (`CardPageV3`):**

    | Field           | Type            | Example |
    | --------------- | --------------- | ------- |
    | `content`       | array of CardV3 |         |
    | `totalElements` | integer         |         |
    | `totalPages`    | integer         |         |
    | `size`          | integer         |         |
    | `number`        | integer         |         |

    ### `POST /api/v3/cards`

    Create card (v3)

    **Request Body (`CreateCardRequestV3`):**

    | Field          | Type             | Example                                |
    | -------------- | ---------------- | -------------------------------------- |
    | `type`         | string (enum)    | `VIRTUAL`/`PHYSICAL`                   |
    | `alias`        | string           | `Card Name`                            |
    | `userUuid`     | string (uuid)    | `a0c82a20-ac09-4cfd-b429-d0623585911e` |
    | `threshold`    | number (decimal) | `1000`                                 |
    | `businessType` | string (enum)    | `BUSINESS`/`WORLD_ELITE`               |
    | `periodicity`  | string (enum)    | `MONTHLY`/`DAILY`                      |

    ### `GET /api/v3/cards/{uuid}`

    Get card by UUID (v3)

    **Parameters:**

    | Parameter | In   | Type          | Required | Description |
    | --------- | ---- | ------------- | -------- | ----------- |
    | `uuid`    | path | string (uuid) | ✅        |             |

    **Response Schema (`CardV3`):**

    | Field          | Type             | Example                                                    |
    | -------------- | ---------------- | ---------------------------------------------------------- |
    | `uuid`         | string (uuid)    | `a0c82a20-ac09-4cfd-b429-d0623585911e`                     |
    | `claraStatus`  | string           | `ACTIVE`                                                   |
    | `status`       | string           | `ACTIVE`, `LOCKED`, `MASTER_LOCKED`, `CANCELLED`           |
    | `lockCode`     | string           | `UNLOCKED`, `TEMPORAL_LOCKED`                              |
    | `alias`        | string           | `Card Name`                                                |
    | `threshold`    | number (decimal) | `1000`                                                     |
    | `periodicity`  | string           | `MONTHLY`, `DAILY`                                         |
    | `maskedPan`    | string           | `514509******5946`                                         |
    | `type`         | string           | `MASTER_VIRTUAL`, `MASTER_CORPORATE`, `MASTER_WORLD_ELITE` |
    | `user`         | object           | `{uuid, fullName, username, links}`                        |
    | `cvv`          | string           | `705` — only present on `GET /{uuid}`                      |
    | `expiryDate`   | string           | `12/30` — only present on `GET /{uuid}`                    |
    | `numberOnCard` | string           | `5109790205009579` — only present on `GET /{uuid}`         |
    | `links`        | array of Link    |                                                            |

    ### `DELETE /api/v3/cards/{uuid}`

    Delete card (v3)

    **Parameters:**

    | Parameter | In   | Type          | Required | Description |
    | --------- | ---- | ------------- | -------- | ----------- |
    | `uuid`    | path | string (uuid) | ✅        |             |

    ### `PATCH /api/v3/cards/{uuid}/lock`

    Toggle card lock (v3)

    **Parameters:**

    | Parameter | In   | Type          | Required | Description |
    | --------- | ---- | ------------- | -------- | ----------- |
    | `uuid`    | path | string (uuid) | ✅        |             |

    **Request Body (`ToggleCardLockRequest`):**

    | Field      | Type    | Required | Example                           |
    | ---------- | ------- | -------- | --------------------------------- |
    | `locked`   | boolean | ✅        | `true` to lock, `false` to unlock |
    | `lockCode` | integer | ✅        | `16`                              |

    **Response (`202 Accepted`):** `{batchId, id, uuid, status: "UPDATED"}`

    ### `PATCH /api/v3/cards/{uuid}/threshold`

    Update card threshold (v3)

    **Parameters:**

    | Parameter | In   | Type          | Required | Description |
    | --------- | ---- | ------------- | -------- | ----------- |
    | `uuid`    | path | string (uuid) | ✅        |             |

    **Request Body (`UpdateCardThresholdRequest`):**

    | Field       | Type             | Example |
    | ----------- | ---------------- | ------- |
    | `threshold` | number (decimal) | `5000`  |

    ### `POST /api/v3/cards/bulk-create`

    Bulk create cards (v3)

    **Request Body (`BulkCreateCardRequest`):**

    | Field   | Type                         | Example |
    | ------- | ---------------------------- | ------- |
    | `cards` | array of CreateCardRequestV3 |         |

    ### `POST /api/v3/cards/delete`

    Bulk delete cards (v3)

    **Request Body (`BulkDeleteCardsRequest`):**

    | Field   | Type            | Example |
    | ------- | --------------- | ------- |
    | `uuids` | array of string |         |

    ### `PATCH /api/v3/cards/lock`

    Bulk toggle card lock (v3). Returns `202 Accepted` — async, result delivered via webhook.

    **Request Body:**

    | Field               | Type  | Required | Description                                        |
    | ------------------- | ----- | -------- | -------------------------------------------------- |
    | `cardsLockRequests` | array | ✅        | Each item: `{uuid, locked: boolean, lockCode: 16}` |

    **Example:**

    ```json theme={null}
    {
      "cardsLockRequests": [
        { "uuid": "dd9bf99c-648b-419d-8316-32201ef91289", "locked": true, "lockCode": 16 }
      ]
    }
    ```

    **Response (`202`):**

    ```json theme={null}
    {
      "id": "9e9fe2c0-a194-4b81-9025-df45753b0f79",
      "message": "Your request has been received but still in progress, you will get the response via webhook",
      "cardsLockResponses": [
        { "batchId": "9e9fe2c0-...", "id": "0dae8e5c-...", "uuid": "dd9bf99c-...", "status": "SENT" }
      ]
    }
    ```

    ### `PATCH /api/v3/cards/threshold`

    Bulk update card thresholds (v3). Returns `202 Accepted` — async, result delivered via webhook.

    **Request Body:**

    | Field                          | Type  | Required | Description                            |
    | ------------------------------ | ----- | -------- | -------------------------------------- |
    | `updateCardsThresholdRequests` | array | ✅        | Each item: `{uuid, threshold: number}` |

    **Example:**

    ```json theme={null}
    {
      "updateCardsThresholdRequests": [
        { "uuid": "dd9bf99c-648b-419d-8316-32201ef91289", "threshold": 1500.00 }
      ]
    }
    ```

    **Response (`202`):**

    ```json theme={null}
    {
      "id": "85e01930-3d69-4aed-85b6-0080d6792c44",
      "message": "Your request has been received but still in progress, you will get the response via webhook",
      "updateCardsThresholdResponses": [
        { "batchId": "85e01930-...", "id": "88d35238-...", "uuid": "dd9bf99c-...", "status": "SENT" }
      ]
    }
    ```
  </Tab>

  <Tab title="v2">
    ## Creating Cards

    **Requirements:**

    * New user creation. To enable the Clara API, you must create a user with the Company Owner role. This user is essential for creating resources in Clara. Separating this user helps distinguish actions from automated processes and those from other users on the platform, enhancing clarity and accountability.
    * mTLS. Our API employs a secure authentication process that requires you to configure the client making the calls with the certificates provided when the API is enabled. This ensures a high level of security and a 2FA for your communications.

    **Required Fields:**

    * `type`: 1 = physical, 2 = virtual
    * `alias`: A nickname or identifier for the card
    * `userUUID`: The unique identifier for the user in Clara (Find from user's endpoint)
    * `threshold`: Max limit - with Minimum amount of R$50 (BR), $500 (MX), \$100,000 (CO)
    * `periodicityType`: 1 = monthly, 2 = daily

    **Examples:**

    ***Create: Virtual Card (MX)***

    ```json theme={null}
    {
        "type": 2,
        "alias": "Example",
        "userUUID": "42c7cc6b-06f7-46b8-b4f5-e876fbf57335",
        "threshold": 500,
        "periodicityType": 2
    }
    ```

    In this example:

    * The type 2 indicates a virtual card.
    * The alias helps identify the card.
    * The threshold is 500 (MXN), allowing daily spending.
    * The periodicity type 2 means the limit resets daily.

    ***Create: Physical Card (MX)**:*

    ```json theme={null}
    {
        "type": 1,
        "alias": "Example",
        "userUUID": "42c7cc6b-06f7-46b8-b4f5-e876fbf57335",
        "threshold": 500,
        "periodicityType": 1
    }
    ```

    In this example:

    * The type 1 indicates a physical card.
    * The alias helps identify the card.
    * The threshold is 500 (MXN), allowing monthly spending.
    * The periodicity type 1 means the limit resets monthly.

    <br />

    ## Limitations

    * Threshold must be ≤ company credit line
    * User must be active (email verified, 2FA)
    * Only one card creation per user at a time (prevent fraud) - If you need multiple cards for one user, wait until the current card creation is complete before making another request.
    * Monitor card count to avoid max limit - Clara has a maximum limit on valid cards for each company (active or locked)

    <br />

    ## Card Operations

    * \*\*Update limit (threshold): \*\*Card must be active, additionally, the new limit for this card must not exceed the company's total limit.
    * \*\*Lock card: \*\*Must be active (card locked - modifications not applied, with exception for card cancelling)
    * \*\*Unlock card: \*\*Must be locked
    * \*\*Cancel card: \*\*To free up space to create new cards (you can cancel cards that are active or locked) - After cancellation, the card can't be used or recovered.

    <br />

    ## Card Life Cycle

    Creation → Activation (physical) → Active → Locking → Canceling → Closure

    * **Creation:** The card is generated and assigned to a user. At this stage, details such as card type, limits, and user information are defined.
    * \*\*Activation: \*\*The card is activated for use. This may involve confirming the user's identity and setting up necessary security measures. This process is only for physical cards, virtual cards are created and active by default.
    * \*\*Active: \*\*The card is actively used for transactions. Users can spend up to the defined limits. In this stage, changes can be made to the card, such as adjusting spending limits, updating user information, and configuring the spending rules.
    * **Locking:** If necessary, the card can be locked to prevent further transactions. This is often done in cases of suspected fraud, lost cards, or by direct action from the user.
    * \*\*Canceling: \*\*By canceling the card, it becomes deactivated and no longer valid for transactions. This may occur when a user no longer needs the card or when it reaches its expiration date.
    * \*\*Closure: \*\*The card is officially closed and removed from the system. This typically follows deactivation and is the final step in the card's life cycle.

    **Notes:** Cards that are not canceled or closed are considered valid and count toward the maximum number of valid cards; once a card is canceled, it can't be recovered.

    <br />

    ## Virtual Card

    \*\*Note: \*\*Virtual cards are created as "active" by default, no activation is needed.

    <br />

    ## Physical Card

    **Note:** The statuses "locked," "master locked," and "Clara blocked" indicate the same state for the card but originate from different sources:

    ### Lock States Explained

    * **Locked** = by user
    * **Master Locked** = by manager or user's hierarchy
    * **Clara Blocked** = by our internal team

    ### Status Change Events

    * Lock (Locked, Master Locked, Clara Blocked), unlock, or cancel by client, manager, or Clara

    <br />

    ## Common Errors

    * **`B013 Threshold exceeds company limit`**: This error occurs when the threshold (limit) set for a card exceeds the allowable amount, or the card limit exceeds the company's overall limit.
    * **`B022 User is not activated`**: This error may occur if the user has been deleted or is not active on the Clara platform, like a new user.
    * **`B033 Core service failure`**: This error indicates an internal failure and further investigation is needed to identify the problem.
    * **`This user already has a card in the creation queue. Try again in 2 minutes`**: This error occurs because cards for the same user cannot be created concurrently. To solve this issue, you need to wait for the current card creation process to finish or allow the timeout for creation to occur in our system.

    ***

    ## Endpoint Reference

    ### `GET /api/v2/cards`

    List all cards (v2)

    **Parameters:**

    | Parameter     | In    | Type          | Required | Description                                          |
    | ------------- | ----- | ------------- | -------- | ---------------------------------------------------- |
    | `userUuid`    | query | string (uuid) |          | Filter by user UUID                                  |
    | `username`    | query | string        |          | Filter by username                                   |
    | `status`      | query | string        |          | Filter by card status                                |
    | `periodicity` | query | string        |          | Filter by periodicity                                |
    | `type`        | query | string        |          | Filter by card type                                  |
    | `userErpId`   | query | string        |          | Filter by user ERP ID (only if userUuid not present) |

    **Response Schema (`CardPageV3`):**

    | Field           | Type            | Example |
    | --------------- | --------------- | ------- |
    | `content`       | array of CardV3 |         |
    | `totalElements` | integer         |         |
    | `totalPages`    | integer         |         |
    | `size`          | integer         |         |
    | `number`        | integer         |         |

    ### `GET /api/v2/cards/{uuid}`

    Get card by UUID (v2)

    **Parameters:**

    | Parameter | In   | Type          | Required | Description |
    | --------- | ---- | ------------- | -------- | ----------- |
    | `uuid`    | path | string (uuid) | ✅        |             |

    **Response Schema (`CardV2`):**

    | Field         | Type             | Example                                                                        |
    | ------------- | ---------------- | ------------------------------------------------------------------------------ |
    | `uuid`        | string (uuid)    | `1b23c45c-c678-90f1-abef-efc12fc3d4aa`                                         |
    | `status`      | string           | `ACTIVE`, `LOCKED`, `PENDING_TO_COLLECT_DUE_TO_SERVICE_CANCELLATION`           |
    | `claraStatus` | string           | `ACTIVE`, `DELETED`                                                            |
    | `lockCode`    | string           | `UNLOCKED`, `TEMPORAL_LOCKED`                                                  |
    | `alias`       | string           | `Marketing Card`                                                               |
    | `threshold`   | number (decimal) | `100.0`                                                                        |
    | `periodicity` | string           | `MONTHLY`, `DAILY`                                                             |
    | `brand`       | string           | `MASTER`                                                                       |
    | `maskedPan`   | string           | `514501******3540`                                                             |
    | `type`        | string           | `MASTER_VIRTUAL`, `MASTER_CORPORATE`, `MASTER_WORLD_ELITE`                     |
    | `user`        | object           | `{uuid, userFullName, username, role, taxIdentifier, erpId, status, location}` |

    ### `GET /api/v2/cards/{cardUuid}/configurations`

    Get card configurations (v2)

    **Parameters:**

    | Parameter  | In   | Type          | Required | Description |
    | ---------- | ---- | ------------- | -------- | ----------- |
    | `cardUuid` | path | string (uuid) | ✅        |             |

    ### `PUT /api/v2/cards/{cardUuid}/configurations`

    Update card configurations (v2)

    **Parameters:**

    | Parameter  | In   | Type          | Required | Description |
    | ---------- | ---- | ------------- | -------- | ----------- |
    | `cardUuid` | path | string (uuid) | ✅        |             |

    **Request Body (`CardConfigurationRequest`):**

    | Field          | Type                         | Example |
    | -------------- | ---------------------------- | ------- |
    | `period`       | object (CardConfigPeriod)    |         |
    | `atmCashLimit` | number (decimal)             | `5000`  |
    | `weekdays`     | object (CardConfigWeekdays)  |         |
    | `merchants`    | object (CardConfigMerchants) |         |
  </Tab>

  <Tab title="v1">
    <Warning>v1 is legacy and read-only. Migrate to v3 for full card management.</Warning>

    ## What is the Transactions API?

    The **Cards API v1** allows you to retrieve information about the physical and virtual cards issued to users in your Clara account. This includes the card's metadata such as type, status, last four digits, and issuing user.

    This version of the API is **read-only**, and is commonly used to:

    * Display or validate card metadata in internal tools
    * Reconcile cards with transactions or user profiles
    * Generate reports or dashboards based on card status or type

    🆚 Note: For card creation, updates, and controls, use [Cards API v2](#).

    <br />

    ## Available Endpoints

    | Operation         | Endpoint           | Method |
    | ----------------- | ------------------ | ------ |
    | Find all cards    | `/v1/cards`        | GET    |
    | Find card by UUID | `/v1/cards/{uuid}` | GET    |

    <br />

    ## Find all cards

    Use this endpoint to **list all cards** associated with your account. The response includes card type, status, last digits, and user references.

    ### Endpoint

    `GET /v1/cards`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X GET \
    "https://public-api.mx.clara.com/api/v1/cards" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    ### Sample JSON Response

    ```json JSON theme={null}
    {
      "content": [
        {
          "uuid": "bedeeadc-1138-4123-a2f9-84bd81c434a7",
          "status": "ACTIVE",
          "alias": "Marketing Card",
          "threshold": 1000.0,
          "periodicity": "MONTHLY",
          "cardNumber": "510979******4423",
          "type": "MASTER_CORPORATE",
          "userUuid": "75d45b4f-91db-4ca2-a204-c9ac2d04b031"
        }
      ],
      "totalElements": 528,
      "totalPages": 264,
      "size": 2,
      "number": 0
    }
    ```

    <br />

    ## Find cards by UUID

    Use this endpoint to retrieve detailed information for a specific card using its unique identifier.

    ### Endpoint

    `GET /v1/cards/{uuid}`

    ### cURL Request

    ```curl cURL theme={null}
    curl -X GET \
    "https://public-api.mx.clara.com/api/v1/cards/card-001" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
    ```

    ### Sample JSON Response

    ```json JSON theme={null}
    {
      "uuid": "bedeeadc-1138-4123-a2f9-84bd81c434a7",
      "status": "ACTIVE",
      "alias": "Marketing Card",
      "threshold": 1000.0,
      "periodicity": "MONTHLY",
      "cardNumber": "510979******4423",
      "type": "MASTER_CORPORATE",
      "userUuid": "75d45b4f-91db-4ca2-a204-c9ac2d04b031"
    }
    ```

    <br />

    **💡 Tip:** Use the userUuid to cross-reference card ownership and track usage per employee.

    \*\*⚠️ Note: \*\*This API version does not support locking, unlocking, issuing, or updating cards — only retrieval.

    ***

    ## Endpoint Reference

    ### `GET /api/v1/cards`

    Find all cards

    **Parameters:**

    | Parameter         | In    | Type                                                                                          | Required | Description                                                   |
    | ----------------- | ----- | --------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------- |
    | `page`            | query | integer                                                                                       |          | Zero-based page index (0..N)                                  |
    | `size`            | query | integer                                                                                       |          | The size of the page to be returned                           |
    | `userUuid`        | query | string                                                                                        |          | UUID of the user for which to retrieve cards                  |
    | `status`          | query | string                                                                                        |          | Filter by card status (e.g., `ACTIVE`, `LOCKED`, `CANCELLED`) |
    | `periodicityType` | query | enum: `DAILY`/`MONTHLY`                                                                       |          | Periodicity of the cards                                      |
    | `type`            | query | enum: `MASTER_WORLD_ELITE`/`MASTER_CORPORATE`/`MASTER_VIRTUAL`/`VISA_PHYSICAL`/`VISA_VIRTUAL` |          | Type of the cards                                             |

    ### `GET /api/v1/cards/{uuid}`

    Find cards by UUID

    **Parameters:**

    | Parameter | In   | Type   | Required | Description |
    | --------- | ---- | ------ | -------- | ----------- |
    | `uuid`    | path | string | ✅        | Card UUID   |
  </Tab>
</Tabs>