Create spend rules for a card

Use this when you need to restrict what a card can be used for, beyond what its profile already allows.

It sets the card-level spend rules for the managed card identified by the id path parameter. Rules apply at two levels: profile-level rules are configured in the Multi Portal and apply to every card on the profile, and card-level rules are set here for one card. Both are evaluated on each authorization, and card-level rules can only narrow what the profile permits, never widen it.

Call this once per card. If the card already has card-level rules, the request fails with SPEND_RULE_ALREADY_SET. Use Update spend rules instead.

Fields

Where the card can be used

allowedMerchantCategories and blockedMerchantCategories filter by merchant category code (MCC), allowedMerchantIds and blockedMerchantIds by merchant, and allowedMerchantCountries and blockedMerchantCountries by ISO 3166-1 alpha-2 country code. The merchant and MCC lists hold up to 200 entries each; the country lists hold up to 50.

An allow list means "only these": anything not on it is declined. A block list means "not these." Where a value appears on both lists, the block list wins.

How the card can be used

allowContactless, allowAtm, allowECommerce, allowCashback, and allowCreditAuthorisations switch whole categories of transaction on or off for the card.

Transaction size

minTransactionAmount and maxTransactionAmount are expressed in the card's currency. A transaction outside that range is declined.

Spend limits

spendLimit is a list of amount-and-interval pairs, for example 50000 daily and 500000 monthly. All limits are checked, so the tightest one binds. Each interval is a fixed UTC calendar window (DAILY, WEEKLY, MONTHLY, QUARTERLY, YEARLY), except ALWAYS, which is a lifetime cap on the card. Use startTimestamp to delay when a limit starts applying.

Each value must be in the card's currency, or the request fails with SPEND_LIMIT_CURRENCY_DIFFERENT_FROM_CARD_CURRENCY. You can't set two limits on the same interval (SPEND_LIMIT_DUPLICATE_INTERVAL).

Rollover

Set rolloverPolicy.rolloverNegative to true on a spend limit to carry overspend into subsequent intervals. A negative available-to-spend amount is then deducted from each new interval until the balance becomes positive. It is disabled by default and configured separately for each card.