Flexible transaction controls

The Pismo platform enables you to create different types and levels of flexible transaction controls (flex controls). You can use the Flex controls API to create and manage flex controls that restrict your customers' financial operations, such as spending mode or maximum spending limits. You can also use the Pismo Control Center to manage flex controls through a user interface.

After you create the control, the Pismo platform evaluates it whenever there are authorizations on your customers' accounts. Evaluations happen on an account or customer level, not a control level. Depending on the control and other conditions, the platform may deny the financial transactions performed by customers. During different operations, the platform generates flex controls data events asynchronously.

📘

To use flex controls in network transactions, you must enable the Send rules authorization program parameter.

Create flex control

When creating a new flex control, you must first define the applicability level. This table shows the different applicability levels.

Applicability levelControls created at this level apply to ...
ProgramAll accounts within a program
AccountSelected accounts
CustomerSelected cardholders
CardSelected cards
  • To create and manage flex controls at the program level, use the Pismo Control Center.
  • To create flex controls at the account level, use the account endpoint: rules/v1/accounts/{accountId}/flex-controls.
  • To create flex controls at the customer or card level, use the customer endpoint: rules/v1/customers/{customerId}/flex-controls.

After choosing the applicability level, select which conditions need to be considered at the time of evaluation. A control can be one of two types: restriction or cumulative.

Condition typeDescriptionRequirements
restrictionRestriction controls are designed to restrict where, how, or when customers can perform their financial operations.

For example, restriction controls can deny purchases by merchant category code (MCC), by entry mode, or within a time window.

The restriction control type is more straightforward since it defines the control condition(s) without any additional calculations.
The type value in the payload request is restriction.

To restrict an operation, the restriction control must specify:

- at least one condition in the conditions array.
- the required values for attribute, operator, and value in the condition.
cumulativeCumulative controls are designed to restrict how customers can spend on their financial operations.

Cumulative spending controls calculate and maintain values of past transactions.

These calculated values can either be a counter, such as the number of transactions, or the sum amount of transactions (for example, $1000 over a week).
The type value in the request can be:

- spending_limit to restrict the maximum total amount that can be transacted during an specific period.
- usage_limit to evaluate the quantity of transactions.The cumulative control type must also specify the max_limit.The limit_duration and reset_period parameters are optional but they are linked with the behavior of max_limit.

POST <URL>/rules/v1/accounts/{accountId}/flex-controls
POST <URL>/rules/v1/customers/{customerId}/flex-controls

In the request, send the following:

  • account ID or the customer ID.
  • the tenant ID in the header.
  • a combination of the following attributes to define the flexible transaction control.

For full details, see the API references for creating a flex control by customer ID or by account ID.

Body parameters

For both restriction and cumulative types of controls, you can define the following body parameters.

Body parameterDescription
typeCondition type. One of the following:
- restriction
- spending_limit
- usage_limit
nameDescriptive name of the control.
processing_codesCode used to establish which type of operation is evaluated; for example, purchase, transfer, cash-out.
deny_codeDenial code to return when the evaluation matches the control condition.
currency_codeCurrency code (ISO-4217) for the flex control.
time_zoneCode from the IANA time zone database, such as "America/New_York". This attribute is used to evaluate the flex control using the desired time zone for condition attributes such as week_day, month_day, time_now and reset_period. If time_zone is empty, the control is evaluated using the UTC time zone.

For both types of controls, you can create a condition in the conditions array that includes:

  • operator that determines the type of condition evaluation.
  • value to evaluate.
  • attribute to evaluate with any of the following parameters specified in the following table.
Body parameterDescription
balanceThe maximum balance amount allowed in an account. Due to fiscal restrictions in some countries, the user cannot have more than a certain amount in the account. When the balance value is defined, the control validates any process of entering money into that account, evaluates the account balance at the time of the transaction, and denies any inflow of money above the amount defined in the balance value.
amountA numeric value that indicates the amount of the operation performed by the user.
merchant_category_codeMerchant Category Code (MCC) is a four-digit number used to describe a merchant's primary business activities.
Note: Valid only for card network operations. For a control to be valid, you must enter a code specified by the Mastercard/Visa card network.
week_dayA day of the week when the operation is performed. For example, Mon-Fri.
month_dayA day of the month when the operation is performed. Commonly used to delimit operations on holidays. For example, 25/December.
time_nowA restriction window used to establish the time when the operation is performed, defined in the Coordinated Universal Time (UTC 0) zone. For example, 10:59PM-06:59AM window specifies restrictions that apply from 11PM to 7AM in the UTC 0 time.
entry_modeA code used to establish the mode of purchase where the operation is carried out. For example, contactless, chip, e-commerce.
The entry_mode value is a three-character field:

- The first two characters define the PAN entry mode (for example, 05 - chip, 07 - contactless, 10 - card on file (COF), and so on). Each payment network has its own specification for these codes. For example, Visa.
- The third character defines the PIN capability of the terminal (for example, 0 - unspecified, 1 - terminal has PIN entry capability, 2 - terminal doesn't have PIN entry capability, 8 - terminal has PIN entry capability but PIN pad is not currently operative).
For example, a purchase with the contactless payment method at a terminal that has no PIN entry capability would be 072.
Note: Valid only for card network operations. For a control to be valid, you must enter a code specified by the Mastercard/Visa card network.
country_codeThree-letter country code (ISO 3166-1) for the flex control condition.
currency_codeThree-letter currency code (ISO-4217) for the flex control condition.
merchant_idAn identifier used to establish the merchant.
Note: Valid only for card network operations. For a control to be valid, you must enter a code specified by the Mastercard/Visa card network.

For cumulative controls, the following additional settings are available to specify how your customer can spend on their financial operations.

Body parameterDescription
max_limitSpecifies the maximum amount allowed in financial transactions according to the type chosen. Once this condition is met or exceeded, the subsequent operations are denied.

This field is required for cumulative controls.
limit_durationSpecifies the duration period in which this condition is calculated. For example, day, week, or month.

This field is required for cumulative controls.
reset_periodThis object allows you to specify a reset period for accumulators based on the duration in limit_duration. When this field is set, it t must follow the RFC 3339 pattern from ISO 8601. When reset_period changes, the avaliable_limit is reset.

This field is optional for cumulative controls.

For flex controls defined for an account, the following additional settings are available.

Body parameterDescription
beneficiary_idString identifier for the beneficiary related to the account.

Note: Beneficiaries are entities linked to an account that have customer data for use in financial transactions (such as the account number or the customer’s last name). For example, with a registered beneficiary, you can bind specific rules (flex controls) to increase or decrease the defined limit of an account's transactions to the beneficiary's account.

Endpoints related to beneficiaries are a part of the Bank accounts API.
override_controlsList of existing spending controls (IDs) that the new spending control will override. These controls will be ignored to only evaluate the new control.

Get all controls

You can retrieve all defined flex controls via the following endpoints.

To retrieve all controls registered for a customer, call the following GET endpoint:
GET <URL>/rules/v1/customers/{customerId}/flex-controls

To retrieve all controls registered for an account, call the following GET endpoint:
GET <URL>/rules/v1/accounts/{accountId}/flex-controls

In addition to the customer ID or account ID, you also need to provide the tenant ID in the request header. This request returns all flex controls that have been defined both on the global program level and on the account, customer, or card level. For full details, see the API references for getting flex controls by customer ID and by account ID.

The following example returns four defined controls:

  • Three global program controls that are being managed by the system on the program level, as indicated by the "customized": false" parameter.
  • One control that has been customized and is being managed by you.
{
        "id": "transaction-10000-rule",
        "rule_reference_id": "6b81e6b0-c3e2-4758-9ce5-7bfa2b296474",
        "type": "restriction",
        "name": "transaction-10000-rule",
        "description": "This control restricts the transaction when value is greater than $BRL 10000.00.",
        "conditions": [
            {
                "id": "44fc71d7-4f51-404a-aa85-4cda6302bca7",
                "attribute": "amount",
                "operator": "gte",
                "value": "1000000"
            }
        ],
        "currency_code": "BRL",
        "deny_code": "ERR_VAL_TRANSACTION",
        "active": true,
        "customized": false
    },
    {
        "id": "restrict-mcc-0742",
        "rule_reference_id": "cf4b4376-cd23-4189-9877-6bcf54306365",
        "type": "restriction",
        "name": "restrict-mcc-0742",
        "description": "This control restricts the transaction when mcc is 0742.",
        "conditions": [
            {
                "id": "64a50b0e-fe89-4573-ae45-469ae7f40509",
                "attribute": "merchant_category_code",
                "operator": "eq",
                "value": "0742"
            }
        ],
        "currency_code": "BRL",
        "deny_code": "ERR_VAL_TRANSACTION_MCC",
        "active": false,
        "customized": false
    },
    {
        "id": "purchase-1M-rule",
        "type": "spending_limit",
        "name": "purchase-1M-rule",
        "description": "This control restricts the maximum amount that the user can spend $BRL 11000.00.",
        "currency_code": "BRL",
        "max_limit": 1100000,
        "available_limit": 1100000,
        "limit_duration": "P1M",
        "deny_code": "ERR_MAX_SPENDING_LIMIT",
        "reset_datetime": "2022-02-24T22:05:30Z",
        "active": true,
        "customized": false
    },
    {
        "id": "ecd6a1e7-a283-49d6-aa88-d8f4a9601f7b",
        "type": "restriction",
        "name": "restrict_airlines_mcc",
        "conditions": [
            {
                "id": "950b76b9-eefb-41be-bde7-ef82a8c11821",
                "attribute": "merchant_category_code",
                "operator": "in",
                "value": "4511,4722"
            }
        ],
        "deny_code": "RESTRICT_BY_MCC",
        "active": true,
        "customized": true
    }
]

Get specific control

To get a specific control, call one of the following GET endpoints and pass:

  • the customer ID or account ID, respectively
  • the tenant ID in the header
  • spending limit ID

For full details, see the API references to get a specific controls by customer/card or by account.

GET <URL>/rules/v1/customers/{customerId}/flex-controls/{flexControlId}

{
		"id": "89cbdadc-860b-4275-a5cd-d9d892fd3869",
		"type": "global",
		"processing_codes": [
			"07000",
			"07001"
		],
		"rule_reference_id": "purchase-1M",
		"name": "purchase-24",
		"account_id": 8988000,
		"customer_id": 99999999,
		"card_ids": [
			11111,
			22222
		],
		"currency_code": "BRL",
		"max_limit": 49999,
		"limit_duration": "P1M",
		"reset_datetime": "2022-03-08T21:19:55+00:00",
		"available_limit": 49999,
		"conditions": [
			{
				"attribute": "balance",
				"operator": "gt",
				"value": "10000"
			}
		],
		"active": true,
		"deny_code": "ERR_VAL_BALANCE"
	}

GET <URL>/rules/v1/accounts/{accountId}/flex-controls/{flexControlId}

{
  "id": "9cbdadc-860b-4275-a5cd-d9d892fd3869",
  "rule_reference_id": "purchase-1M",
  "type": "spending_limit",
  "name": "purchase-1M",
  "description": "This control limits the maximum amount that the user account can spend for airlines (MCC 4511) each month",
  "processing_codes": [
        "07000",
        "07001"
    ],
  "currency_code": "BRL",
  "max_limit": 49999,
  "available_limit": 300,
  "time_zone": "America/New_York",
  "conditions": [
    {
    "id": "b4930a4d-e2c4-4fdc-9803-c83dec3a30d1",
    "attribute": "merchant_category_code",
    "operator": "eq",
    "value": "4511"
    }
  ],
  "limit_duration": "P1M",
  "reset_period": {
    "month_day": 1,
    "time": "05:00AM"
  },
  "reset_datetime": "2022-03-08T21:19:55+00:00",
  "active": true,
  "customized": true
}

📘

Note that this response contains the time_zone field with the America/New_York value. In this case, the platform evaluates the time attribute using the specified New York time zone. If the time_zone field is not set, the platform evaluates the flex control using the UTC time zone.

Update control

You can update a flex control and its conditions by using the following PATCH endpoints.

📘

  • For global program controls, "customized": false indicates that the platform manages this control and updates it by the internal process. During the evaluation flow, the platform checks if there are any changes in any globally defined controls. If there are, the conditions and attributes are updated with the new values. The platform applies these changes to new and existing accounts.
  • For all account/customer/card controls that have been created by the flex-control endpoints, "customized": true indicates that the internal process must not update this flex control during the evaluation flow. This control can be updated only by using the PATCH endpoint.

For full details, see the API references for updating controls by customer/card or by account.

To change controls by customer/card, call the following PATCH endpoint:
PATCH <URL>/rules/v1/customers/{customerId}/flex-controls/{flexControlId}

To change controls by account, call the following PATCH endpoint:
PATCH <URL>/rules/v1/accounts/{accountId}/flex-controls/{flexControlId}

Provide the tenant ID in the header, the customer or account ID, and the spending limit ID. In the request, you can provide only the parameters that you'd like to change. For example, you can update the MCC to add another code.

{
    "conditions": [
        {
            "attribute": "merchant_category_code",
            "operator": "in",
            "value": "4511,4722,3615"
        }
    ]
}

Another common use case for this endpoint is to disable a control. To disable a control, call the PATCH endpoint and set the attribute active to false.

{
  "active": false
}

You can also potentially change a global program control so you can manage it instead. To do so, set the attribute customized to true.

{
  "customized": true
}

📘

Once you create the control, you can't change its type.

Disable control

By default, when a new control is created, the attribute active is set to true . To disable a control, you need to use the PATCH endpoint to set the attribute active to false, as illustrated in the previous section.

If you want to disable any control at the global program level, you need to submit a request to the Pismo support team to change the active status parameter to false.

Simulate control creation

  1. Set up the credit card collection according to the instructions on the Sample project page.
  2. In the credit card collection, execute the following calls:
  • Platform > Server Authentication to authenticate to the server.
  • Platform > Acquisitions > Create an application form to create a new account.
  • Enduser > Server Login with Account to authenticate with an account.
  • Enduser > Cards > virtual > Create virtual card to create a new virtual card.
  • Enduser > Cards > BrandedCardPurchaseSimulator > Branded authorization simulation to define a new card purchase. The platform evaluates and clears the transaction. No controls are restricting the transaction from proceeding. The system should return the response_code of 00 to indicate that the purchase was authorized successfully.
  1. List existing controls. For more information, see Get all controls.
    GET <URL>/rules/v1/accounts/{accountId}/flex-controls

  2. Define a new control. For more information, see Create flex control and Examples.

{
  "type": "restriction",
  "name": "restrict-entry-mode-051",
  "description": "Restrict purchase for chipset card",
  "processing_codes": [
    "00"
  ],
  "conditions": [
    {
      "attribute": "entry_mode",
      "operator": "eq",
      "value": "051"
    }
  ],
  "deny_code": "RESTRICT_ENTRY_MODE_051", 
  "active": true
}
  1. Call the POST endpoint to create a new control.
    POST <URL>/rules/v1/accounts/{accountId}/flex-controls

  2. Build a test transaction. For more information, see Simulate authorizations.

{
  "card_id":"xxxxxx",
  "local_amount":50,
  "local_currency":"986",
  "settlement_amount":50,
  "entry_mode":"051",
  "merchant":{
    "name":"Wolley's Wool",
    "city":"New York",
    "country":"USA"
   },
   "processing_code":"00",
   "mti":"0100",
   "account_type":"20",
   "invoice_address":"101 Main St, City",
   "authorization_code":"xxxx"
}
  1. Call the authorization simulation endpoint.
    POST <URL>/networktransactions/v1/authorizations

Examples

Deny purchase by merchant category

This example denies purchase by merchant category code (MCC), following the ISO 18245 standard, for airlines carriers (4511) and travel agencies and tour operators (4722). This flex control evaluates and restricts purchase when the 4511, 4722 MCC values are present in the request.

To create this type of restrictive flex control:

  1. In the request payload, set the type to restriction.
  2. In conditions, define:
    -attribute to be merchant_category_code
    -operator to be in (include), which evaluates the list of values and returns true if the specified property value is in the specified object.
    -value to list applicable MCC codes. In this case, 4511, 4722.
  3. Call the following POST endpoint and provide the account ID and tenant ID in the header.

POST <URL>/rules/v1/accounts/{accountId}/flex-controls

{
    "type": "restriction",
    "name": "restrict_airlines_and_travel",
    "conditions": [
        {
            "attribute": "merchant_category_code",
            "operator": "in",
            "value": "4511,4722"
        }
    ],
    "deny_code": "RESTRICT_BY_MCC",
    "active": true
}
{
    "id": "ecd6a1e7-a283-49d6-aa88-d8f4a9601f7b",
    "type": "restriction",
    "name": "restrict_airlines_and_travel",
    "conditions": [
        {
            "id": "950b76b9-eefb-41be-bde7-ef82a8c11821",
            "attribute": "merchant_category_code",
            "operator": "in",
            "value": "4511,4722"
        }
    ],
    "deny_code": "RESTRICT_BY_MCC",
    "active": true,
    "customized": true
}

Deny purchase by entry mode

This example denies purchases by entry mode for contactless purchases on a terminal that is not capable of receiving a password. The entry mode in this case is 072, where the first two characters 07 indicate contactless mode and the third character 2 indicates that the terminal doesn't have PIN entry capability.

{
    "type": "restriction",
    "name": "restrict_purchase_contactless",
    "conditions": [
        {
            "attribute": "entry_mode",
            "operator": "eq",
            "value": "072"
        }
    ],
    "deny_code": "RESTRICT_BY_ENTRY_MODE",
    "active": true
}

Define maximum usage limit

This example creates the maximum usage flex control for limiting the quantity of purchases per month to 100 transactions. The processing code 00 references purchase transactions.

{
  "type": "usage_limit",
  "name": "limit_purchase_per_month",
  "processing_codes": [
    "00"
  ],
  "max_limit": 100,
  "limit_duration": "P1M",
  "deny_code": "MAX_USAGE_P1M",
  "active": true
}

Restrict purchase authorizations within a time window

This example restricts purchases made after 11pm and before 7am and allows purchases within the 7am-11pm time window.

{
  "type": "restriction",
  "name": "restrict_purchase",
  "description": "Restrict purchase from 11:00PM to 07:00AM",
  "processing_codes": [
    "00"
  ],
  "conditions": [
     {
      "attribute": "time_now",
      "operator": "in",
      "value": "10:59PM-06:59AM"
    }
  ],
  "deny_code": "RESTRICT_BY_TIME",
  "active": true
}

Limit the quantity of purchase transactions within a time window

This example limits the number of purchases to 10 transactions during the night from 11:00PM to 07:00AM.

{
  "type": "usage_limit",
  "name": "limit_purchase_night",
  "description": "Limit purchase to 10 transaction during night from 11:00PM to 07:00AM",
  "processing_codes": [
    "00"
  ],
  "conditions": [
    {
      "attribute": "time_now",
      "operator": "in",
      "value": "10:59PM-06:59AM"
    }
  ],
  "max_limit": 10,
  "limit_duration": "PT6H",
  "deny_code": "MAX_USAGE_PURCHASE_NIGHT",
  "active": true
}

Create flex control per transaction type

You can use the processing_codes filter to:

  • evaluate a flex control for a certain transaction type.
  • apply a flex control to several transaction types.
  • create different flex controls for different transaction types.

The following example creates a flex control for purchase (00) and withdrawal (10) transactions.

{
  "type": "spending_limit",
  "name": "limit_amount_purchase",
  "processing_codes": [
    "00", "10"
  ],
  "max_limit": 49999,
  "limit_duration": "P1M",
  "deny_code": "MAX_VALUE_AMOUNT_P1M",
  "active": true
}

Create flex control for a beneficiary overriding existing controls

The following example:

  • creates flex control for an account.
  • defines a beneficiary.
  • lists existing controls that will be overridden by the new spending control.

POST <URL>/rules/v1/accounts/{accountId}/flex-controls

{
  "type": "spending_limit",
  "name": "Purchase 1 Month credit card",
  "beneficiary_id": "a10efbf9-e67c-4c3c-b52c-d1218427a81b",
  "override_controls": [
    "9186bafe-a077-4cab-bc42-08db41410d52",
    "12565ce9-050f-41d5-8c63-8d1a13c817ae"
  ],
  "processing_codes": [
    "007000"
  ],
  "max_limit": 49999,
  "limit_duration": "P1M",
  "deny_code": "MAX_VALUE_P1M",
  "active": true
}