Skip to main content
This guide covers the full employee card lifecycle: onboarding a new cardholder, issuing a virtual card, configuring optional spending restrictions, and safely offboarding when an employee departs.

​
Prerequisites

  • A valid Bearer token and mTLS client certificate. See Authentication.
  • The employee’s name, email, and role.

​
Step 1: Look up the user

Before creating a card, check whether the user already exists in Clara. Query by email to avoid duplicates. 
curl --request GET \
  "https://public-api.mx.clara.com/api/v3/users?email=ana.garcia@acme.com" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key
Response: 
{
  "totalElements": 1,
  "content": [
    {
      "uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
      "fullName": "Ana García",
      "email": "ana.garcia@acme.com",
      "role": "EMPLOYEE",
      "status": "ACTIVE"
    }
  ]
}
If totalElements is 0, the user doesn’t exist yet — create them first via the Users API, then proceed with the uuid returned.

​
Step 2: Issue a virtual card

Create a virtual card assigned to the user. Set a threshold (spending limit) and a periodicity that resets it automatically. 
curl --request POST \
  "https://public-api.mx.clara.com/api/v3/cards" \
  --header "Authorization: Bearer <TOKEN>" \
  --header "Content-Type: application/json" \
  --cert client.crt \
  --key client.key \
  --data '{
    "type": "VIRTUAL",
    "alias": "Ana García — Travel",
    "userUuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
    "threshold": 5000,
    "periodicity": "MONTHLY"
  }'
Response: 
{
  "uuid": "5d1e2f83-1c90-4c34-9400-bfef9ac85c6e",
  "alias": "Ana García — Travel",
  "status": { "code": "ACTIVE", "description": "Active" },
  "maskedPan": "514509******5946",
  "threshold": 5000,
  "periodicity": { "type": "MONTHLY" },
  "type": { "format": "VIRTUAL" },
  "user": {
    "uuid": "a0c82a20-ac09-4cfd-b429-d0623585911e",
    "name": "Ana García"
  }
}
Save the card uuid — you’ll need it for configuration and status checks.
FieldNotes
typeVIRTUAL or PHYSICAL
aliasA human-readable label shown in the Clara dashboard
thresholdAmount in your company’s currency (MXN, BRL, or COP)
periodicityMONTHLY, WEEKLY, or DAILY — determines when the limit resets
businessTypeOptional: BUSINESS or WORLD_ELITE

​
Step 3: Apply spending restrictions (optional)

Use the Card Configurations API to add time, day-of-week, or merchant category restrictions. All fields are optional and can be combined. 
curl --request POST \
  "https://public-api.mx.clara.com/api/v2/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e/configurations" \
  --header "Authorization: Bearer <TOKEN>" \
  --header "Content-Type: application/json" \
  --cert client.crt \
  --key client.key \
  --data '{
    "weekdays": {
      "values": ["SATURDAY", "SUNDAY"],
      "allowedDaysOfUse": false
    },
    "merchants": {
      "values": ["TRANSPORTATION", "CAR_RENTALS", "TRAVEL_AND_LODGING", "FOOD"],
      "allowedMerchants": true
    }
  }'
This example restricts usage to weekdays only and allows spending solely at transportation, car rental, hotel, and food merchants. Common configurations:
RestrictionHow
Block weekendsweekdays.values: ["SATURDAY","SUNDAY"], allowedDaysOfUse: false
Restrict to specific MCC categoriesmerchants.values: [...], allowedMerchants: true
Time window (e.g., 9am–6pm)period.startTime: "09:00", endTime: "18:00"
Auto-delete after a tripperiod.endDate: "YYYY-MM-DD", enableAutoDeletion: true
See Card Configurations for the full list of merchant categories and options.

​
Step 4: Confirm the card is active

Verify the card is ready before distributing it to the employee. 
curl --request GET \
  "https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key
Confirm status.code is "ACTIVE" before sharing the card details with the cardholder.

​
Adjust the spending limit

To raise or lower the threshold at any time: 
curl --request PATCH \
  "https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e/threshold" \
  --header "Authorization: Bearer <TOKEN>" \
  --header "Content-Type: application/json" \
  --cert client.crt \
  --key client.key \
  --data '{ "threshold": 8000 }'

​
Offboarding

When an employee leaves, first lock the card to immediately block usage, then delete it once you’ve confirmed there are no pending transactions. Lock the card (immediately blocks all charges): 
curl --request PATCH \
  "https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e/lock" \
  --header "Authorization: Bearer <TOKEN>" \
  --header "Content-Type: application/json" \
  --cert client.crt \
  --key client.key \
  --data '{ "lockCode": 16 }'
Delete the card (permanent, cannot be recovered): 
curl --request DELETE \
  "https://public-api.mx.clara.com/api/v3/cards/5d1e2f83-1c90-4c34-9400-bfef9ac85c6e" \
  --header "Authorization: Bearer <TOKEN>" \
  --cert client.crt \
  --key client.key
Deleted cards cannot be recovered. Lock first, wait 24–48 hours to confirm no settlements are pending, then delete.