Cards API: how to use it, and its restrictions

How to Use It

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 Information to Create a Card

• Type: Specifies whether the card is virtual or physical. Use 1 for a physical card (plastic card sent by mail) and 2 for a virtual card.
• Alias: A nickname or identifier for the card.
• User UUID: The unique identifier for the user in Clara. You can find this in the user’s endpoint.
• Threshold: The maximum spending limit, which has a minimum amount of:
  • R$ 50.00 for Brazil
  • MXN $ 500.00 for Mexico
  • Col$ 100000.00 for Colombia
• Periodicity Type: Indicates how often the spending limit resets. Use 1 for monthly and 2 for daily.

Examples

Here’s an example of how to create a virtual card in Mexico:

JSON

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

Here’s an example of how to create a physical card in Mexico:

JSON

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

• The threshold must be lower than the total company's credit line.
• The user must be active in Clara, which requires email confirmation and two-factor authentication (2FA).
• You can request multiple card creation sequentially, but not for the same user. This prevents fraud. If you need multiple cards for one user, wait until the current card creation is complete before making another request.
• Clara has a maximum limit on valid cards for each company. It's crucial to monitor your cards, whether they are active or locked, to ensure the smooth creation of new cards without interruptions.

Updating limits

• The card must be active to update a card's limit (threshold). Additionally, the new limit for this card must not exceed the company's total limit.

Locking / Unlocking

• To lock a card, it must be in an active status. Once the card is locked modifications can't be applied, except for canceling the card.
• To unlock the card, it must be in the locked status.

Canceling

Since Clara has a maximum limit on the number of valid cards (including active and locked cards), this operation is necessary to free up space and ensure you can continue creating new cards.

• The states that allow you to cancel a card are active and locked.
• After a card is canceled it can't be used or recovered.

Card Life Cycle

The card life cycle includes the following stages:

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

• Locked: This action is initiated by the cardholder.
• Master Locked: This is performed by the manager or someone else in the cardholder's hierarchy.
• Clara Blocked: This action is taken by our internal team.

All three statuses mean that the card is in the locked state, just with different authorities behind the action.

Events that can change the status of a card

Locking a card

• The client performs a lock in the card (Locked)
• The card was locked by the manager (Master Locked)
• Clara locked the card due to fraud prevention (Clara Blocked)

Unlocking a card

• The client performs an unlock in the card
• The manager unlocked the card
• Clara unlocked the card

Canceling a card

• The client performs a canceling in the card
• The active period of the card ended

Well-Known Errors

• "B013, Threshold is greater than company threshold" 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, Users 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 API exception" 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.