Advanced Card Limits

The Advanced Card Limits feature lets partners configure multiple concurrent spend limits on a single card. Each limit has its own monetary cap, renewal frequency, and optional scope that targets a subset of transactions (by merchant category, acceptance method, or ATM).

Prerequisites

The ADVANCED_CARD_LIMITS_FEATURE feature module must be enabled on the payment program. Contact Pliant to activate this for your program. ATM-scoped limits additionally require the ATM withdrawal feature enabled.

How limits stack

A card always has one primary limit (the total spend cap). Additional limits sit beneath it and apply only to the transactions they are scoped to. A transaction must pass all applicable limits to be authorized.

Example: A EUR 5,000 monthly primary limit with a EUR 200 monthly ATM limit means the cardholder can withdraw up to EUR 200 in cash, while total spend (cash + purchases) cannot exceed EUR 5,000.

An unscoped additional limit (scope: null) acts as a secondary total cap with a different frequency, for example a EUR 500 weekly sub-limit on top of a EUR 3,000 monthly total.

Scope options

By merchant category

Restricts the limit to transactions at merchants matching the specified categories. Multiple categories may be combined in a single limit.

By acceptance method

Restricts the limit to transactions made via the specified payment methods.

Available scope.acceptanceMethods values: ONLINE, CONTACTLESS, CHIP_DIP, MAGNETIC_STRIPE, MOBILE_WALLET, MANUAL_ENTRY, OTHER, NOT_AVAILABLE

ATM withdrawals

Set scope.atmWithdrawal: true to target cash withdrawal transactions only.

Combining scope fields

Multiple scope fields within one limit are AND-ed together. For example, setting both categories: ["FOOD_AND_DRINKS"] and acceptanceMethods: ["ONLINE"] restricts the limit to online food and drink orders only.

Renewal frequencies

PER_TRANSACTION is only valid for additional limits, not for the primary card limit.

Transaction count cap

Use maxTransactionCount to cap the number of transactions per renewal period regardless of amount. Combine with limit to enforce both a spend cap and a count cap simultaneously.

Creating a card with additional limits

Pass the optional additionalLimits array in POST /api/cards (v2.1.0). The field is optional; existing integrations without it are unaffected.

Example 1: ATM monthly limit

{
  "additionalLimits": [
    {
      "limitRenewFrequency": "MONTHLY",
      "limit": { "value": 20000, "currency": "EUR" },
      "scope": { "atmWithdrawal": true }
    }
  ]
}

Example 2: Travel and accommodation, capped monthly

{
  "additionalLimits": [
    {
      "limitRenewFrequency": "MONTHLY",
      "limit": { "value": 200000, "currency": "EUR" },
      "scope": { "categories": ["TRAVEL_AND_ACCOMMODATION"] }
    }
  ]
}

Example 3: Online spend only, weekly cap

{
  "additionalLimits": [
    {
      "limitRenewFrequency": "WEEKLY",
      "limit": { "value": 50000, "currency": "EUR" },
      "scope": { "acceptanceMethods": ["ONLINE"] }
    }
  ]
}

Example 4: Food and drinks, max 10 transactions per day

{
  "additionalLimits": [
    {
      "limitRenewFrequency": "DAILY",
      "limit": { "value": 8000, "currency": "EUR" },
      "maxTransactionCount": 10,
      "scope": { "categories": ["FOOD_AND_DRINKS"] }
    }
  ]
}

Example 5: Multiple limits on one card

{
  "additionalLimits": [
    {
      "limitRenewFrequency": "MONTHLY",
      "limit": { "value": 20000, "currency": "EUR" },
      "scope": { "atmWithdrawal": true }
    },
    {
      "limitRenewFrequency": "MONTHLY",
      "limit": { "value": 150000, "currency": "EUR" },
      "scope": { "categories": ["TRAVEL_AND_ACCOMMODATION"] }
    },
    {
      "limitRenewFrequency": "WEEKLY",
      "limit": { "value": 30000, "currency": "EUR" },
      "scope": { "categories": ["FOOD_AND_DRINKS", "ENTERTAINMENT_AND_WELLNESS"] }
    }
  ]
}

Reading limits from card details

GET /api/cards/{cardId} and the batch endpoint (POST /api/cards/details) return additionalLimits including current balance info. GET /api/cards/requests/{cardRequestId} also returns additionalLimits for card requests.

GET /api/cards (the list endpoint) intentionally does not include additionalLimits. It only returns basic card fields. Use the dedicated card details endpoint instead.

Partners can also track applied additional limits via the CARD_LIMITS_CHANGED callback, which fires whenever additional limits are added, updated, or removed on a card.

Example response from POST /api/cards/{cardId}:

{
  "additionalLimits": [
    {
      "id": "a1b2c3d4-...",
      "limitRenewFrequency": "MONTHLY",
      "limit": { "value": 20000, "currency": "EUR" },
      "scope": { "atmWithdrawal": true, "categories": [], "acceptanceMethods": [] },
      "balanceInfo": {
        "balance": { "value": 5500, "currency": "EUR" },
        "availableLimit": { "value": 14500, "currency": "EUR" },
        "limitRenewDate": "2026-06-01"
      }
    }
  ]
}

balanceInfo.limitRenewDate is null for TOTAL frequency limits.

Updating additional limits

Use PUT /api/cards/limits/{cardId} with the additionalLimits array:

• Include an entry with id to update an existing limit.
• Include an entry without id to add a new limit.
• Omit an existing limit's entry entirely to remove it.
• Pass [] to remove all additional limits.
• Pass null or omit additionalLimits to leave existing limits unchanged.

Note: The batch limit update endpoint PATCH /api/cards/limits does not support additionalLimits.