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.

Example: Card spending controls UI

Here are some examples of how you could present your customers the option

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

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

    "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

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

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:

Period

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

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:

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

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