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, or after every purchase
• Set spending limits to control how much a card can spend per interval
• Top-up a card back to its original balance after spending

Which fields apply to each card

Every card exposes spending_control_strategy in the GET response, and that value decides which fields of the update act on it:

⚠️

The endpoint accepts every field for every card. A field sent to a card of the other model is stored but has no effect: a spending limit does not restrict a prepaid card, and an allocation does not load a limit_based card. Check spending_control_strategy before choosing which fields to send.

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, spending_control_strategy, and current balance information. Steps 2 and 3 apply to allocation_based cards; step 4 to limit_based cards.

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 minor unit of the card's currency. For CLP (which has no subunit), the value equals the amount in pesos directly: 50.000 CLP = 50000. Currently, allocations are only supported for cards in CLP. See Amounts and currency for the full per-currency table.

📘 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 reload the card back to recurring_allocation_amount_cents. A reload never exceeds the company's available balance or, for a card in a funded budget, the budget's committable_cents. Cards in a tracking budget reload from the company's balance.

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"
  }'

allocation_interval_preference sets when the reload happens:

allocation_priority_preference is required whenever an interval is set. Send null for both to turn recurring allocations off.

⚠️

Each reload counts as a movement of your company's main account. Prepago Los Héroes allows up to 1,000 movements per month between reloads and purchases of that account. Once the limit is reached, reloads of every card are paused until the next month.

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, limit_based cards)

Restrict how much the card can spend per interval. Prepaid (allocation_based) cards ignore these fields: they spend what is allocated to them.

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