Card spending controls

The spending controls feature allows your customers to tailor card spending to fit their needs and enjoy a greater degree of security around their spending. To this end, you can institute the following controls:

• Card controls lists: Inclusion/exclusion controls that determine how customers' cards can be used. 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: These determine how much money can be spent using a customer's card in a certain context or time interval. Examples:

  • Setting a maximum number of daily card transactions at either the individual card level or among all cardholders
  • Setting a maximum amount that can be spent each month

For example, customers may use these controls to:

• Allow/disallow ATM withdrawals
• Allow/disallow e-commerce transactions
• Allow/disallow internal transactions

This guide describes how to implement these controls.

Common data elements

Origin

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

Dimensions

When creating a card spending control, you must specify the dimension of the control. Dimensions determine what kind of control to impose on spending. The value of the dimension depends on the type of card spending control.

Example (card controls list)

In this example, the card controls list will exclude all transactions of type ATM_WITHDRAWAL for all cards that it applies to.

    "exclusion": {               
      "type": "TRANSACTION_TYPE",
      "dimension": [
        "ATM_WITHDRAWAL"
      ]
    }

If you used the inclusion object instead of the exclusion object, the card controls list would only allow transactions of type ATM_WITHDRAWAL for all cards that it applies to.

Example (card spending limit control, V2)

When creating a card spending limit control using the V2 method, you can create an array of conditions to apply to the control. Each condition object contains a transaction type and array of dimensions to either include (using the dimension array) or exclude (using the excluded_dimension array). Note that within a single condition, you may only use one of these arrays. You can use multiple conditions within the same control to create a more precise restriction on the customer's card spending.

In the example below, a daily limit of 2000 Euro is applied for OCT transactions (specified in the first condition) at merchants with all category codes except crypto (specified in the second condition).

"limit": {
        "period": "DAILY",
        "amount": 20000,
        "conditions": [
            {
                "type": "TRANSACTION_TYPE",
                "dimension": [
                    "OCT"
                ]
            },
            {
                "type": "MERCHANT_CATEGORY_CODE",
                "excluded_dimension": [
                    "crypto"
                ]
            }
        ]
    }

Example (card spending limit control, V1)

In the example below, spending with merchants with the category 5411 would be limited to 1000 Euros per hour (or 5 transactions per hour).

    "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
      // OR
      "count": 5              // Number of limited transactions that may be conducted within time period
    }

List of dimensions

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

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.

Card spending limit controls

V2 update

Please note that there are currently two versions of the card spending limit controls endpoints: V1 and V2. Solaris recommends implementing the V2 endpoints.

The V2 endpoints introduce the conditions array to the card spending control object. This allows you to specify more than one type to restrict within a single control, which is not possible with V1. For example, you could create a single control to apply to a transaction type within multiple countries:

"limit": {
        "period": "DAILY",
        "amount": 30000,
        "conditions": [
            {
                "type": "TRANSACTION_TYPE",
                "dimension": [
                    "OCT"
                ]
            },
            {
                "type": "MERCHANT_COUNTRY",
                "excluded_dimension": [
                    "FR",
                    "IT",
                    "ES"
                ]
            }
        ]
    }

V2 spending limit control structure

V1 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:

Period

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

Amount

You can specify an amount (in Euro cents) that may be spent within the context of the limit. Note that you cannot specify both an amount and a count within the same limit.

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:

{
   "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:

• POST Create card controls list
• GET Retrieve a card controls list
• GET Index card controls lists
• DELETE Remove a card controls list

Card spending limit control endpoints

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

V2 endpoints

• POST Create card spending limit control (V2)
• GET Retrieve a card spending limit control (V2)
• GET Index card spending limit controls (V2)
• DELETE Remove a card spending limit control (V2)

V1 endpoints

• POST Create card spending limit control (V1)
• GET Retrieve a card spending limit control (V1)
• GET Index card spending limit controls (V1)
• DELETE Remove a card spending limit control (V1)