Guides

💳 Cards API: How to Use It, and Its Restrictions

Here is a full guide to card creation, management, and lifecycle

Suggest Edits

🛠 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)

{
    "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):

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

⚠️ 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 → 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.


💳 Virtual Card

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


💳 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

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

Updated about 15 hours ago