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 Pismo Control Center to manage program-level flex controls through a user interface.

You can define a flex control at each entity's respective level. For a program, define the flex control at the program level to affect all accounts. To apply a flex control for a specific account, customer, or card, define the flex control at that level. For example, define a card flex control at the cards level. After choosing the applicability level, select which conditions need to be considered at the time of evaluation.

A condition can be one of two types.

• Cumulative controls are used to restrict how many transactions a customer can perform or how much they can spend in a given time period. 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 of the transactions.
• Restriction controls are used to restrict where, how, or when customers can perform 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 defines the control condition(s) without any additional calculations.

After you create a control, the Pismo platform uses it to evaluate authorizations on your customers' accounts. Evaluations happen at the account or customer level, not at the control level. Depending on the control and other conditions, the platform might deny a transaction. During flex control operations, the platform generates flex control data events asynchronously.

📘

Flex controls can be applied to Pix transactions.

📘

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

Progressive update

When an account is created, the Pismo platform copies all flex controls from the program to the accounts, so every account has a copy of the flex controls attached to that program.

When a program-level flex control is changed, the platform does not immediately update flex controls copied to accounts in the original program. The platform waits for a flex control evaluation during the authorization flow to detect the differences between the account and program flex controls, and then incrementally updates the flex controls. For this update to occur, the flex control of the account must not be customized.

📘

To apply controls at the program level, you must use Pismo Control Center.

Simulate control creation

You can use a Postman collection to simulate and test out a flex control before applying it.

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, ensuring that 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.

3. List existing controls. For more information, refer to Get all controls.

4. Define a new control. For more information, refer to 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
}

5. Call Create account flex control.

6. Build a test transaction. For more information, refer to 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"
}

7. Call Simulate authorization.

Examples

Deny purchase by merchant category

This example denies purchases by merchant category code (MCC), for airlines carriers (4511) and travel agencies/tour operators (4722). The flex control evaluates and restricts a 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 type to restriction.
2. In conditions, set:
   -attribute = merchant_category_code
   -operator = in (include). This setting causes the Pismo platform to return true if merchant_category_code is equal to any of the MCC codes listed in value.
   -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.

{
    "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 a 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 denies purchases made between 11:00 PM and 07:00 AM and allows purchases within the 07:01 AM - 10: 59 PM time window.

{
  "type": "restriction",
  "name": "restrict_purchase",
  "description": "Deny purchases between 11:00 PM and 07:00 AM",
  "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 between 11:00 PM to 07:00 AM.

{
  "type": "usage_limit",
  "name": "limit_purchase_night",
  "description": "Limit purchases to 10 transactions between 11:00 PM to 07:00 AM",
  "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

Use the processing_codes filter for the following purposes.

• 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

This example does the following.

• Creates flex control for an account.
• Defines a beneficiary.
• Lists existing controls that the new spending control overrides.

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

Pix and accounts

If you want to enable a different time range and limit for each account, set up the following control using the Update account flex control endpoint. In this example, the start time is changed from 8 PM to 10 PM and the limit is decreased from R$1,000 to R$500 for a specific account:

{  
    "conditions": [  
        {  
            "id": "1c61caa5-ab07-48dd-9f56-8419090116d6",  
            "attribute": "time_now",  
            "operator": "in",  
            "value": "10:00PM-6:00AM"  
        }  
    ],  
    "max_limit": 50000,  
    "active": true,  
    "customized": true  
}