Cards

​

Creating Cards

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

• 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

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

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

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

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

​

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)

​

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.

​

Card Life Cycle

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

​

Virtual Card

​

Physical Card

​

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

​

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

​

GET /api/v2/cards/{uuid}

​

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

​

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

​

What is the Transactions API?

• 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

​

Available Endpoints

​

Find all cards

​

Endpoint

​

cURL Request

curl -X GET \
"https://public-api.mx.clara.com/api/v1/cards" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​

Sample JSON Response

{
  "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
}

​

Find cards by UUID

​

Endpoint

​

cURL Request

curl -X GET \
"https://public-api.mx.clara.com/api/v1/cards/card-001" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN"

​

Sample JSON Response

{
  "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"
}

​

Endpoint Reference

​

GET /api/v1/cards

​

GET /api/v1/cards/{uuid}