Flexible transaction controls

Learn about how to create and manage flexible transaction controls in the Pismo platform.

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.

After the control is created, 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.

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
globalonly to the selected program.
accountonly to the selected account.
customeronly to the selected cardholder.
cardonly to the selected card.
  • To create flex controls at the global level, submit a request to the Pismo support team.
  • 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 type

Description

Requirements

restriction

Restriction 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.

cumulative

Cumulative 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 allowed amount of the transaction.
  • 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 parameter

Description

type

Condition type. One of the following:

  • restriction
  • spending_limit
  • usage_limit

name

The descriptive name of the control.

processing_codes

A code used to establish which type of operation is evaluated; for example, purchase, transfer, cash-out.

deny_code

The denial code to return when the evaluation matches the control condition.

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 parameter

Description

balance

The 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.

amount

A numeric value that indicates the amount of the operation performed by the user.

merchant_category_code

Merchant 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_day

A day of the week when the operation is performed. For example, Mon-Fri.

month_day

A day of the month when the operation is performed. Commonly used to delimit operations on holidays. For example, 25/December.

time_now

A 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_mode

A 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.

currency_code

A currency code (ISO-4217) for the control.

merchant_id

An 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.

card_id

A card identifier.

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

Body parameter

Description

max_limit

Specifies 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_duration

Specifies the duration period in which this condition is calculated. For example, day, week, or month.

This field is required for cumulative controls.

reset_period

This 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 parameter

Description

beneficiary_id

String 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 International Bank Accounts API.

override_controls

List 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 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 limit 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,
  "conditions": [
    {
    "id": "b4930a4d-e2c4-4fdc-9803-c83dec3a30d1",
    "attribute": "merchant_category_code",
    "operator": "eq",
    "value": "4511"
    }
  ],
  "limit_duration": "P1M",
  "reset_period": {
    "month_day": 1,
    "utc_time": "05:00AM"
  },
  "reset_datetime": "2022-03-08T21:19:55+00:00",
  "active": true,
  "customized": true
}

Update control

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

📘

  • For global 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 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 level, you need to submit a request to the Pismo support team to change the active status parameter to false.

Flex controls events

Flex controls generate the following events.

Event

Description

evaluation_requested-1

Evaluation requested
This event is sent every time an evaluation request is completed. It contains information about the parameters received to evaluate and the result of the evaluation. It is triggered by a direct request from different APIs.

evaluation_rollback_requested-1

Evaluation rollback requested
This event is sent after completing a rollback from an evaluation. This request comes from an internal queue. It only contains the evaluation’s id/CID from the evaluation process.

template_created-1

Template created
This event is sent every time a template is created. It contains all information from the request. You need to contact the Pismo support representative to create a template.

template_updated-1

Template updated
This event is sent every time a template is updated. It contains all the template information, with new values already in place. You need to contact the Pismo support representative to update a template.

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 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
}

Related pages

API reference to manage customer spending limits
API reference / Get all customer flex controls
API reference / Create customer flex control
API reference / Update customer flex control
API reference / Get customer flex control

API reference to manage account spending limits
API reference / Get all account flex controls
API reference / Create account flex control
API reference / Update account flex control
API reference / Get account flex control


Did this page help you?