Cards Configurations API: how to use it

Types of configurations

Clara offers several options to configure the cards, including:

• Usage periods (with the option to automatically delete the card after the defined period)
• ATM withdrawals (only for physical cards)
• Days of the week
• Vendor categories

These configurations can be combined and used simultaneously.

Usage periods

This configuration is intended for card usage on scheduled dates, with the option to automatically delete the card after the defined period. The start and end date indicate the window this card will be active, and the start and end time indicate what time of the day it will be possible to use it.

Required fields:

• startDate: Specifies the starting date to enable the card for usage, in the format YYYY-MM-DD.
• endDate: Specifies the ending date to enable the card for usage, in the format YYYY-MM-DD.
• startTime: Specifies the starting time to use the card date to enable the card for usage, in the format HH:MM
• endTime: Specifies the ending time to use the card date to enable the card for usage, in the format HH:MM
• enableAutoDeletion: A boolean flag that indicates if the card will be automatically deleted after the period expiry.

Note: if the enableAutoDeletion is set, the card will be deleted even with other configurations.

In this example, the card will be active from December 1st, 2024, to December 31st, 2024, from 8 a.m. to 8 p.m. After the end date, it will be automatically deleted.

JSON

{
  "period": {
    "startDate": "2024-12-01",
    "endDate": "2024-12-31",
    "startTime": "08:00",
    "endTime": "20:00",
    "enableAutoDeletion": true
  }
}

ATM withdrawals

This configuration applies only to physical cards and allows the cardholder to withdraw the specified amount from an ATM.

Required fields:

• atmCashLimit: Specifies the amount that can be withdrawn from ATM.

Note: the currency is always the currency where the contract is signed. MXN to Mexico, BRL to Brazil, and COL to Colombia.

In this example it allows the cardholder to withdraw $ 100 MXN

JSON

{
    "atmCashLimit": 100
}

Days of the week

This configuration is indicated to cards daily operations and without a scheduled date to end.

Required fields:

• values: A list of values that indicates the days of the week. Allowed values, always in uppercase.
  • WEEKDAYS (Indicates from Monday to Friday)
  • MONDAY
  • TUESDAY
  • WEDNESDAY
  • THURSDAY
  • FRIDAY
  • SATURDAY
  • SUNDAY
• allowedDaysOfUse: A boolean flag that indicates if the values in the list are days allowed to use or not.

In this case, we have a card that can be used from Monday to Friday, but it can't be used on the weekends.

JSON

{
  "weekdays": {
    "values": ["SATURDAY", "SUNDAY"],
    "allowedDaysOfUse": false
  }
}

Vendor categories

This configuration is used to restrict the category of the vendor where the card can make expenses.

Required fields:

• values: A list of values that indicates the categories. Allowed values, always in uppercase.
  • RETAIL
  • OFFICE
  • OTHERS
  • HEALTH
  • ENTERTAINMENT
  • SPECIALTY_STORES
  • TEXTILE_PRODUCTS
  • SOFTWARE_AND_HARDWARE
  • ELECTRONICS
  • SUBSCRIPTIONS
  • FOOD
  • BARS_OR_ALCOHOLIC_BEVERAGES
  • GOVERNMENT_PAYMENTS
  • CHARITY_AND_SOCIAL
  • PROFESSIONAL_SERVICES
  • REAL_ESTATE
  • TRANSPORTATION
  • CAR_RENTALS
  • TRAVEL_AND_LODGING
  • FUEL_GOODS
  • COMMUNICATION
  • DIGITAL_ADS
  • DIGITAL_COMMERCE
  • CONTRACTORS_AND_CONSTRUCTION
  • SPECIAL_SERVICES
  • EDUCATION
  • JEWELRY_CASINOS_AND_FINES
• allowedMerchants: A boolean flag that indicates if the values in the list are categories allowed to use or not.

Example:

JSON

{
  "merchants": {
    "values": ["TRANSPORTATION", "CAR_RENTALS", "TRAVEL_AND_LODGING"],
    "allowedMerchants": true
  }
}

Combining configurations

Example: Consider a typical use case where an employee is traveling for work from December 1st, 2024, to December 7th, 2024. In this scenario, the card will be active during the first week of December, with expenses allowed only on weekdays, from 8 a.m. to 8 p.m., and within specific categories such as car rentals, hotels, buses, and taxis. After this period, the card will be automatically deleted.

JSON

{
 "period": {
    "startDate": "2024-12-01",
    "endDate": "2024-12-07",
    "startTime": "08:00",
    "endTime": "20:00",
    "enableAutoDeletion": true
  },
  "weekdays": {
    "values": ["SATURDAY", "SUNDAY"],
    "allowedDaysOfUse": false
  },
	"merchants": {
    "values": ["TRANSPORTATION", "CAR_RENTALS", "TRAVEL_AND_LODGING"],
    "allowedMerchants": true
  }
}