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:
  • 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:
  • benefitCardAccount

Cards

• Extended fields on /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:
  • personal

Payments

• When benefit card accounts are funded from the main account, payments are marked as INTERNAL_TRANSFER
• Documentation clarified on /get-payments-detail

Cardholders

• Updated endpoints to support new cardholder data fields (personal/delivery address, nationality, birthdate):
  • /get-cardholder-details → show new fields
  • /update-cardholders → allow editing new fields
  • /register-cardholders & /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)

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

For details please check out our dedicated guide for benefit cards.