Provision Cards for Employees

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.

Field	Notes
`type`	`VIRTUAL` or `PHYSICAL`
`alias`	A human-readable label shown in the Clara dashboard
`threshold`	Amount in your company’s currency (MXN, BRL, or COP)
`periodicity`	`MONTHLY`, `WEEKLY`, or `DAILY` — determines when the limit resets
`businessType`	Optional: `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:

Restriction	How
Block weekends	`weekdays.values: ["SATURDAY","SUNDAY"]`, `allowedDaysOfUse: false`
Restrict to specific MCC categories	`merchants.values: [...]`, `allowedMerchants: true`
Time window (e.g., 9am–6pm)	`period.startTime: "09:00"`, `endTime: "18:00"`
Auto-delete after a trip	`period.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.

Overview

Conventions

Guides

Resources

API Reference

MCP

VCN

Provision Cards for Employees

Prerequisites

Step 1: Look up the user

Step 2: Issue a virtual card

Step 3: Apply spending restrictions (optional)

Step 4: Confirm the card is active

Adjust the spending limit

Offboarding

​Prerequisites

​Step 1: Look up the user

​Step 2: Issue a virtual card

​Step 3: Apply spending restrictions (optional)

​Step 4: Confirm the card is active

​Adjust the spending limit

​Offboarding

​Related

Prerequisites

Step 1: Look up the user

Step 2: Issue a virtual card

Step 3: Apply spending restrictions (optional)

Step 4: Confirm the card is active

Adjust the spending limit

Offboarding

Related