Card Allocations 💳

Load funds onto your Cardda cards programmatically via API.

How It Works

Cardda cards support fund allocation through the PATCH /v1/vendor_cards/:id endpoint. You can:

• Allocate funds to a card
• Configure recurring allocations on a daily, weekly, monthly, or yearly interval
• Set spending limits to control how much a card can spend per interval
• Top-up a card back to its original balance after spending

Prerequisites

• An API Key with admin or vendor_cards_manage permission
• Your company UUID (passed via the company-id header)

Step by Step

1. List your cards

Find the card you want to load:

curl -X GET https://api.cardda.com/v1/vendor_cards \
  -H "Authorization: Bearer <api_key>" \
  -H "company-id: <company_uuid>"

The response includes each card's id, name, last4, status, and current balance information.

2. Allocate funds

Load 50,000 CLP onto a card:

curl -X PATCH https://api.cardda.com/v1/vendor_cards/<card_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "company-id: <company_uuid>" \
  -H "Content-Type: application/json" \
  -d '{"allocated_amount_preference_cents": 50000}'

📘

All amounts are in the smallest unit of the card's currency. For CLP (which has no decimal subunits), the value equals the amount in pesos directly. For example, 50,000 CLP = 50000. Currently, allocations are only supported for cards in CLP.

📘 Request vs response field names: Request parameters use the _cents suffix (e.g., allocated_amount_preference_cents). The GET endpoints return additional computed fields without the _cents suffix (e.g., allocated_amount_preference, remaining_balance). See the response schema for full details.

3. Configure recurring allocations (optional)

Automatically allocate funds on a schedule:

curl -X PATCH https://api.cardda.com/v1/vendor_cards/<card_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "company-id: <company_uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "recurring_allocation_amount_cents": 50000,
    "allocation_interval_preference": "monthly",
    "allocation_priority_preference": "high"
  }'

Priority levels determine the order in which cards are funded when company balance is distributed:

⚠️

If the company's balance is insufficient to fund all cards, higher-priority cards are funded first. Lower-priority cards may receive a partial allocation or no allocation at all.

4. Set a spending limit (optional)

Restrict how much the card can spend per interval:

curl -X PATCH https://api.cardda.com/v1/vendor_cards/<card_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "company-id: <company_uuid>" \
  -H "Content-Type: application/json" \
  -d '{
    "limit_amount_preference_cents": 100000,
    "limit_interval_preference": "monthly"
  }'

Top-up

If a card was allocated 50,000 CLP and the user has spent 20,000 CLP (actual balance: 30,000 CLP), you can refill it back to 50,000 CLP by sending the same value again:

curl -X PATCH https://api.cardda.com/v1/vendor_cards/<card_id> \
  -H "Authorization: Bearer <api_key>" \
  -H "company-id: <company_uuid>" \
  -H "Content-Type: application/json" \
  -d '{"allocated_amount_preference_cents": 50000}'

The system detects that the requested amount matches the current preference but the actual balance is lower, and automatically tops up the difference.

Permissions

Error Responses