Benefit Card Unload & Termination Balance Transfer

✨ New: Batch Unload Benefit Cards Endpoint

Its not possible to remove funds from benefit cards in batch. This is the counterpart to the existing POST /cards/load endpoint. While load adds funds, unload reclaims unused balances.

Method	Endpoint	Description
`POST`	`/cards/unload`	Unload funds from a batch of benefit cards

Request:

POST /cards/unload

{
  "cards": [
    {
      "cardId": "550e8400-e29b-41d4-a716-446655440000",
      "unloadAmount": {
        "value": 5000,
        "currency": "EUR"
      }
    }
  ]
}

cardId: UUID of the benefit card to unload
unloadAmount.value: Amount in minor units (e.g., 5000 = 50.00 EUR)
unloadAmount.currency: ISO 4217 currency code (must match the Card Account's currency)

Response: 202 Accepted: request is processed asynchronously.

Use cases:

Reclaim remaining balance before card termination (employee leaves)
Remove unused funds at end of benefit period (month/quarter)
Reduce benefit allocation across multiple cards (policy change)
Reverse accidental over-loading (error correction)

⚠️ Pre-conditions

All of the following must be met, or the entire batch is rejected synchronously:

All cards must be active benefit cards (load-based funding type)
All cards must belong to the same Organization
All amounts must be positive and in the Card Account's currency
Amounts must not exceed each card's available balance
No pending unload already in progress for any of the affected cards

🔔 Callbacks

Listen for CARD_BALANCE_UPDATED callback events to track completion of each card's unload.

🔧 Improved: Automatic Balance Transfer on Benefit Card Termination

When a benefit card (load-based) is terminated or expires, the system now automatically transfers remaining funds back to the Organization's main Card Account. This eliminates the need to manually unload cards before termination.

How it works:

Trigger	Timing	Transfer
Card terminated or expired	5 days after termination	Remaining `availableLimit` → main Card Account
Refund/chargeback on terminated card	End of calendar month (rolling check for up to 365 days post-termination)	Refunded transaction amount → main Card Account

After transfer, the card's availableLimit is set to 0.

A new CARD_UNLOADED event appears in the card history.

Questions? Contact your Partner Success manager or email [email protected]