---
agentTools:
  projectIndex: https://partner.getpliant.com/llms.txt
---

# Support for Benefit Cards

We are introducing support for **Benefit Cards** in the CaaS API. This release adds new properties to card configs, card accounts, and cardholder endpoints, introduces region-based controls, and updates the issuance and funding logic when benefit cards are used. Please review the changes below to ensure smooth integration with the updated API.

# Changes of existing endpoints/webhooks

## Card Configs

* **New properties on [`/get-available-cards`](https://partner.getpliant.com/reference/get-available-cards):**
  * `card_properties.funding_type`
    * `CHARGE` – normal non-benefit card
    * `LOAD_BASED_ACCRUING` – unused funds roll over
    * `LOAD_BASED_NON_ACCRUING` – unused funds expire end of month
  * `card_properties.load_based_settings`
    * Defines load config for benefit cards
    * Example:
      ```json
      {
        "fixedAmount": { "amount": 50, "currency": "EUR" },
        "fixedFrequency": "MONTHLY"
      }
      ```
  * `card_properties.expiry_periods_in_months`
    * Defines expiry periods
    * Defaults: `36` months for load-based types and a range of values for other types

***

## Card Accounts

* **New property on [`/get-card-accounts`](https://partner.getpliant.com/reference/get-card-accounts):**
  * `benefitCardAccount`

***

## Cards

* **Extended fields on [`/get-multiple-card-details`](https://partner.getpliant.com/reference/get-multiple-card-details):**
  * `fundingType`
  * `nextLoadDate`

* **Issuing cards (`/issue-card`, `/issue-card-instant`, `/issue-card-instant-with-pci`):**
  * For benefit cards:
    * `limit` and `transactionLimit` must be `0 EUR`
    * `limitFrequency` must be set to `TOTAL`
    * `validFrom`, `validTo` & `validTimezone` must be provided

You can either provide this date before issuing any benefit cards, or issue cards for cardholders who don’t yet have this information. In the latter case, the cardholder must add it later via the API, the Pliant UI, or at any other time. Once the required data is provided, all pending cards will be automatically issued.

***

## Transactions

* **New property on [`/transactions/details`](https://partner.getpliant.com/reference/get-transactions-detail-batch):**
  * `personal`

***

## Payments

* When benefit card accounts are funded from the main account, payments are marked as `INTERNAL_TRANSFER`
* Documentation clarified on [`/get-payments-detail`](https://partner.getpliant.com/reference/get-payments-detail)

***

## Cardholders

* **Updated endpoints to support new cardholder data fields (personal/delivery address, nationality, birthdate):**
  * [`/get-cardholder-details`](https://partner.getpliant.com/reference/get-cardholder-details) → show new fields
  * [`/update-cardholders`](https://partner.getpliant.com/reference/update-cardholders) → allow editing new fields
  * [`/register-cardholders`](https://partner.getpliant.com/reference/register-cardholders) & [`/invite-cardholders`](https://partner.getpliant.com/reference/invite-cardholders) → allow setting new fields

You can either provide this date before issuing any benefit cards, or issue cards for cardholders who don’t yet have this information. In the latter case, the cardholder must add it later via the API, the Pliant UI, or at any other time. Once the required data is provided, all pending cards will be automatically issued.

***

## Important Remarks

* Benefit cards are only available after Pliant activates them for your accounts (card configs + feature module)
* There is a dedicated card account per benefit card which is not visible in the UI
* Benefit cards load **monthly on the 1st** via automated job if scheduled loading is enabled
* Requires sufficient main account balance; otherwise, no funds are transferred
* Load amount = number of active benefit cards × configured load amount
* Optional **region-based controls**:
  * If ZIP present → validated against allowed region (declined if outside)
  * If ZIP missing → transaction accepted

# New endpoint

## Load Benefit Cards

### `POST /cards/loads`

* **Purpose:** Allows you to load funds onto benefit cards manually.
* **Why POST (not PUT):** Loads are **additive events**, not idempotent state changes. Each request creates a new credit event that must be book-kept and audited.

### Request (batch-friendly)

```json
[
  {
    "cardId": "111",
    "load": {
      "amount": { 
        "value": 100,
        "currency": "EUR"
      }
    }
  },
  {
    "cardId": "222",
    "load": {
      "amount": { 
        "value": 50,
        "currency": "EUR"
      }
    }
  }
]
```

For details please check out our dedicated [guide](https://partner.getpliant.com/docs/using-benefit-cards-in-the-caas-api#/) for benefit cards.