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

📘

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 flex controls attached to that program.

When a program-level flex control is changed, the platform does not 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 (customized = true).

📘

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

Create flex control

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

• To create and manage flex controls at the program level, use Pismo Control Center.
• To create flex controls at the account level, call Create account flex control.
• To create flex controls at the customer or card level, call Create customer flex control.

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.

Create account flex control
Create customer flex control

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.

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.

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

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

Get all controls

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

To retrieve all controls registered for a customer, call List customer flex controls.

To retrieve all controls registered for an account, call List account 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 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 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 customer flex control

{
		"id": "89cbdadc-860b-4275-a5cd-d9d892fd3869",
		"type": "spending_limit",
		"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 account flex control

{
  "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 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 program level 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 Update customer flex control.

To change controls by account, call Update account flex control.

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

3. List existing controls. For more information, see Get all controls.

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

5. Call Create account flex control.

6. 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"
}

7. Call Simulate authorization.

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.

Create account flex control

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

Create account flex control

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

In the case you want to enable a different time range and limit for each account, set up the following control using the Update account flex control. In this example, the start time was changed from 8PM to 10PM and the limit is decreased from R$1,000 to R$500 only for this 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  
}