Card spending controls

The spending controls feature allows you to tailor customer card spending to fit your business cases and goals. To this end, it enables you to institute the following controls:

  • Card controls lists: Inclusion/exclusion controls that allow you to determine how cardholders can use their cards. Examples:

    • Including only Germany as an allowed merchant country (i.e., excluding all other countries)
    • Allowing only contactless payment methods (i..e, excluding all other POS entry modes)
  • Card spending limit controls: Allow you to determine how much cardholders can spend in a certain context or time interval. Examples:

    • Setting a maximum number of daily card transactions for all of your customers
    • Setting a maximum amount that a cardholder may spend with each card in their possession each month

This guide describes how to implement these controls.

Common data elements

Origin

This attribute identifies who created the spending control (either PARTNER or SOLARISBANK).

note

You cannot override card spending controls created by Solaris with your own card spending controls.

Dimensions

When creating a card spending control, you must specify the dimension of the control. Dimensions determine the type of control that is imposed on spending as well as the context to which this control applies. For example, The value of the dimension depends on the type of card spending control.

Example (card controls list):

Copy
Copied
    "exclusion": {                  // Include/exclude transactions that fit the dimension
      "type": "TRANSACTION_TYPE",   // The name of the dimension to include/exclude
      "dimension": [
        "ATM_WITHDRAWAL"            // What gets included/excluded within the dimension
      ]
    }

Example (card spending limit control):

Copy
Copied
    "limit": {           // Object that defines how transactions are limited
      "type": "MERCHANT_CATEGORY",  // Type of transactions that are limited
      "dimension": [                // Dimension of transactions within the type that are limited
         "5411"
      ],
      "period": "HOURLY",     // Time period in which transactions are limited
      "amount": 10000,        // Amount imposed on transactions within time period
      "count": 5              // Number of limited transactions that may be conducted within time period
    }

Note that all dimension properties are arrays.

List of dimensions

Name of the dimension (type value) Content of the dimension (dimension values)
MERCHANT_CATEGORY Array of 4-digit numeric codes that correspond with the merchant types to be included or excluded. Examples:
  • 5814 (Fast Food Restaurants)
  • 5912 (Drug Stores and Pharmacies)
  • 5977 (Cosmetic Stores)
POS_ENTRY_MODE Types of POS entry modes for card transactions to be included or excluded. Possible values:
  • MANUAL_PAN_ENTRY
  • MAG_STRIPE
  • CHIP
  • ECOMMERCE
  • CONTACTLESS
  • CREDENTIAL_ON_FILE
  • UNKNOWN
TRANSACTION_TYPE The types of card transactions to be included or excluded. Possible values:
  • PURCHASE
  • ATM_WITHDRAWAL
MERCHANT_COUNTRY A list of ISO3166 2-character country codes that corresponds with countries whose merchants customers can or cannot complete card transactions with.
ACQUIRER_ID An array of identification codes (up to 11 characters) of acquiring institutions for whom card transactions are allowed or denied.
MERCHANT_ID An array of card accepter identification codes (up to 15 characters) for whom card transactions are allowed or denied. Solaris does not have a list of these values; you can retrieve them directly from the merchant or from the acquiring bank.

Card controls lists

Please note the following behaviors of card controls lists:

  • Once you create an inclusion, any card transaction that does not match the inclusion will be excluded.

    • For example, if you create an inclusion with the value of MERCHANT_COUNTRY set to DE, then cardholders will only be able to use their cards for transactions with merchants based in Germany.
    • Conversely, if you create an exclusion with the value of MERCHANT_COUNTRY set to DE, then cardholders will only be able to use their cards for transactions with merchants not based in Germany.

Structure of card controls lists

Card controls list diagram

Data models

Card controls list scopes

While the type and dimension of the card controls list determine what kind of transaction is included or excluded, the scope determines who the control applies to.

For each scope (possible values listed below), you must specify a scope_id. For example, if you want to restrict certain transactions for a business, then you must provide the ID of the business as the value of scope_id.

Scope Definition
PARTNER_CARDS The control applies to the Solaris partner (i.e., you) defined in scope_id.
BUSINESS, BUSINESS_CARDS The control applies to the business type defined in scope_id.
ACCOUNT, ACCOUNT_CARDS The control applies to the customer bank account to which the card is linked, defined in scope_id.
CARDHOLDER, CARDHOLDER_CARDS The control applies to all cards in the possession of the cardholder defined in scope_id.
CARD The control applies to a specific card, defined in scope_id.
NON_BUSINESS_CARDS The control applies to all cards not associated with a business resource (e.g., freelancers and sole proprietors).

Card spending limit controls

Card spending limit control structure

Card spending limit control structure

Data models

Card spending limits have the following unique data models:

Card spending limit control scopes

Note that card spending limit controls use different scopes than card controls lists:

Scope Definition
PARTNER_CARDS The control applies individually to every card you manage.
BUSINESS The control applies to all cards linked to the business defined in scope_id.
BUSINESS_CARDS The control applies individually to each card linked to the business defined in scope_id.
ACCOUNT The control applies to all cards linked to the customer bank account defined in scope_id.
ACCOUNT_CARDS The control applies individually to each card linked to the customer bank account defined in scope_id.
CARDHOLDER The control applies to all cards in the possession of the cardholder defined in scope_id.
CARDHOLDER_CARDS The control applies individually to each card in the possession of the cardholder defined in scope_id.
CARD The control applies to the specific card defined in scope_id.

Period

You can specify a period of time during which the spending limit applies:

Period Description
HOURLY Applies to transactions within an hour (e.g., from 15:00 to 16:00).
MINUTES_60 Applies to transactions within a 60-minute period.
DAILY Applies to transactions within a calendar day.
HOURS_24 Applies to transactions within a 24-hour period.
WEEKLY Applies to transactions within a calendar week (i.e., from Sunday through Saturday).
DAYS_7 Applies to transactions within a 7-day period.
MONTHLY Applies to transactions within a calendar month (e.g., in the month of March).
DAYS_30 Applies to transactions within a 30-day period.
TRANSACTION Applies to all transactions. Note that you may only specify an amount for this type of limit, not a count.

Amount

You can specify an amount that may be spent within the context of the limit (in Euro cents).

Count

You can specify the number of transactions that may be conducted within the context of the limit.

API documentation

CARD_AUTHORIZATION_DECLINE_V2 webhook

Subscribe to the CARD_AUTHORIZATION_DECLINE_V2 webhook to receive notifications whenever a card transaction is declined.

If a card transaction is declined due to a card spending control, then the webhook will return the ID for each card spending control responsible for blocking the payment in the reasons object along with a description of the control.

For example, if a card controls list restricted the transaction, then one of the reasons will have a type of LIST_CONTROL, along with the ID of the card controls list. For card spending limit controls, the type will be SPENDING_LIMIT.

Example payload:

Copy
Copied
{
   "reasons": [
      { "type": "LIST_CONTROL", "id": "rule-id", "message": "Evaluation fails due to the inclusion scope_type={SCOPE_TYPE}, scope_id={SCOPE_ID}, dimension_type={DIMENSION_TYPE}, dimension={DIMENSION} and requested dimension={DIMENSION_PROVIDED}" },
      { "type": "SPENDING_LIMIT", "id": "rule-id", "message": "Evaluation fails due to the exceeding limit scope_type={SCOPE_TYPE}, scope_id={SCOPE_ID}, dimension_type={DIMENSION_TYPE}, dimension={DIMENSION}, period={PERIOD}, amount={AMOUNT}, count={COUNT}" },
    ],

   "card_transaction":{
      "card_id":"f459e5de647e2909c94a7120c4d03557mcrd",
      "type":"PURCHASE",
      "status":"DECLINED",
      "attempted_at":"2019-04-01T12:23:42+00:00",
      "pos_entry_mode":"CHIP",
      "merchant":{
         "country_code":"DE",
         "category_code":"5999",
         "name":"Shady Bob"
      },
      "amount":{
         "currency":"EUR",
         "value":1540,
         "unit":"cents"
      },
      "original_amount":{
         "currency":"EUR",
         "value":1540,
         "unit":"cents"
      }
   }
}

See the CARD_AUTHORIZATION_DECLINE_V2 webhook documentation for more information.

See the transaction declined reasons appendix in the card servicing guide for a full list of decline reasons.

Card controls list endpoints

Click the links below to see the API reference for the endpoints related to card controls lists:

Card spending limit control endpoints

Click the links below to see the API reference for the endpoints related to card spending limit controls: