--- updatedAt: 2026-05-12T17:47:03.000Z --- Fetch the complete documentation index at: https://developers.pismo.io/pismo-docs/llms.txt. Use this file to discover all available pages before exploring further. # List program flex controls List all flex controls grouped by program, with pagination support. Results are ordered by program ID in ascending order. Use the optional `programId` query parameter to filter results to a single program. If `programId` is provided and no templates are found for that program, a `404` is returned. If no `programId` is specified and no templates exist at all, an empty paginated response is returned with status `200`. # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "Core platform - Flex controls", "version": "1.0.0", "description": "Flex controls API", "contact": { "name": "API Support", "url": "https://developers.pismo.io/support/" }, "license": { "name": "Copyright Pismo" } }, "servers": [ { "url": "https://sandbox.pismolabs.io/rules", "description": "Sandbox API server for testing" } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Account access token. Tokens can expire quickly, which can result in an \"Unauthorized\" error.", "bearerFormat": "JWT" } }, "schemas": { "Condition": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Condition ID", "example": "b4930a4d-e2c4-4fdc-9803-c83dec3a30d1" }, "attribute": { "type": "string", "description": "Attribute to evaluate in condition. For `entry_mode`, `merchant_category_code`, and `merchant_id`, these parameters are valid for card network operations. For a control to be valid, you must enter a code specified by the Mastercard/Visa card network.\n* `amount`: Numeric value that indicates the amount of the operation performed by the user\n* `balance`: 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.\n* `country_code`: Three-letter country code (ISO 3166-1) indicating the location where the transaction is initiated or processed.\n* `entry_mode`: A code used to establish the mode of purchase. Valid only for card network operations. For a control to be valid, it must be a code defined by the entire Field 22 (Visa) or DE 22 (Mastercard) or as specified by each card network.\n * Visa: Field 22 contains a 4-digit code indicating the method used to enter the account number and card expiration date (positions 1 and 2) and, if an electronic terminal is used, the capability of the terminal to capture online PINs (position 3) and the last digit (position 4) equal to 0 (unused) for transactions processed through VisaNet. This field is fixed-length with three subfields.\n * Mastercard: DE 22 contains a 3-digit code indicating the method used to enter the account number and card expiration date (positions 1 and 2) and, if an electronic terminal is used, the capability of the terminal to capture online PINs (position 3).\n* `is_device_registered`: Boolean that indicates whether the device used for the operation is registered according to the financial institution's security policies.\n* `is_password_present`: Boolean that indicates whether the password is present in the evaluation request.\n* `is_pin_validated_offline`: Boolean that indicates whether the pin was validated offline in the evaluation request. This is commonly used for offline PIN verification scenarios.\n* `is_physical_card_present`: Boolean that indicates whether a physical card is present in the evaluation request.\n* `is_tra_exemption_requested`: Boolean that indicates whether a TRA (Transaction Risk Assessment) exemption is requested for the transaction.\n* `merchant_category_code`: Merchant Category Code (MCC) is a four-digit number used to describe a merchant's primary business activities. Valid only for card network operations. For a control to be valid, you must enter a code specified by the Mastercard/Visa card network.\n* `merchant_id`: Merchant ID. Valid only for card network operations. For a control to be valid, you must enter a code specified by the Mastercard/Visa card network.\n* `month_day`: Day of the month when the operation is performed. Commonly used to limit operations on holidays. The format is MMM-DD. For example, enter January 25 as \"JAN-25\".\n* `number_of_installments`: Number of installments in the operation\n* `time_now`: Restriction window used to establish the time when the operation is performed, defined in the Coordinated Universal Time (UTC 0) zone. For example, a 10:59 PM-06:59 AM window specifies restrictions that apply from 11 PM to 7 AM in the UTC 0 time.\n* `week_day`: Day of the week when the operation occurs. Use the full lowercase weekday name. Valid values: sunday, monday, tuesday, wednesday, thursday, friday, saturday.\n* `authentication_method`: Enable authorization rules aligned with PSD2 principles. Determine whether restrictions should be applied for specific authentication methods. Valid values are \"password\", \"email\", and \"sms\".\n* `is_token_present`: Boolean that indicates whether a token card is present in the evaluation request.\n* `initiation_mode`: Payment initiation mode.\n - `moto`: Payments made through mail order or telephone.\n - `mit`: Merchant-initiated transactions.\n* `acquirer_country_code`: Three-letter country code (ISO 3166-1) representing the location of the acquiring bank or financial institution.\n* `is_cavv_present`: Boolean indicating that the CAVV field is present. CAVV stands for cardholder authentication verification value.\n* `avr`: String indicating that the transaction is a card network Account Verification Request (AVR) transaction. AVR transactions differ from standard authorizations in that they are typically zero-value and are used for card network verification flows. Currently, the only supported value for this attribute is `mtt`, which is the Mobility & Transport Transaction (MTT) type.\n* `operation_type`: Type of operation being performed. Allowed values are:\n - `debit` - debit transaction\n - `credit` - credit transaction\n - `none` - transaction that doesn't have a financial impact on the account balance, even though an authorization event occurs. These transactions still exist in the authorization flow, but they don't generate balance movement. AVR (Account Verification Request) is one example of this type of transaction with a zero‑amount authorization.\n", "enum": [ "balance", "amount", "merchant_category_code", "week_day", "month_day", "time_now", "entry_mode", "merchant_id", "country_code", "number_of_installments", "is_physical_card_present", "is_device_registered", "is_tra_exemption_requested", "is_pin_validated_offline", "authentication_method", "is_token_present", "initiation_mode", "acquirer_country_code", "is_cavv_present", "avr", "operation_type" ] }, "operator": { "type": "string", "enum": [ "eq", "neq", "lt", "lte", "gt", "gte", "in", "nin", "bt", "in_group", "not_in_group" ], "description": "Condition type evaluation\n* eq - equal to value\n* neq - not equal to value\n* lt - lower than value\n* lte - lower than or equal to value\n* gt - greater than value\n* gte - greater than or equal to value\n* in - includes value\n* nin - does not include value\n* bt - between two values\n* in_group - in attribute group\n* not_in_group - not in attribute group\n" }, "value": { "type": "string", "description": "Value to compare", "example": "10000" } }, "required": [ "attribute", "operator", "value" ] }, "ErrorResponse": { "type": "object", "description": "Error response", "properties": { "message": { "type": "string", "description": "Error description" }, "error_code": { "type": "string", "description": "Error code ID", "deprecated": true }, "code": { "description": "Error code ID", "type": "string" } } }, "LimitDuration": { "type": "string", "description": "Flex control limit period duration (ISO 8601 format).\nFor example, if a flex control sets a spending limit of $500, and `limit_duration` is set to one month (`P1M`), then the user cannot spend more than $500 from the account in any one month period.\nIf `limit_duration` is not set, then the flex control does not accumulate.\n", "example": "P1M" }, "MaxAmount": { "type": "integer", "minimum": 1, "format": "int64", "description": "Maximum accumulated amount allowed. Once met or exceeded, subsequent transactions are declined by the evaluation control flow.\nNote that the value must be calculated as follows.\n\nvalue = floatNumber × 10^X, where X is the number of digits after the decimal separator for the currency defined in ISO 4217.\n\nFor example, if you want to set the value 499.99 for USD currency transactions, where the number of decimal places is 2, you must set the value to `49999` (499.99 × 10²).\n\nIf you want to set the value 499 for JPY currency transactions, where the number of decimal places is 0, you must set the value to `499` (499.0 × 10^0 = 499.0 × 1 - in other words, the value doesn't change).\n", "example": 100000 }, "MaxLimit": { "type": "integer", "minimum": 1, "format": "int64", "description": "Maximum spending limit. Once met or exceeded, any subsequent transactions are declined by evaluation control flow.\nNote that this value is an integer. Since global currencies vary in the number of digits that are allowed after the decimal point, you must convert the actual maximum spending limit into an integer value to use in this field. To do this, use the following formula.\n\nvalue = floatNumber × 10^X, where X is the number of digits after the decimal separator for the currency as defined in ISO 4217.\n\nFor example, if you want to set the value 499.99 for BRL currency transactions, where the number of decimal places is 2, you must set it to `49999` (499.99 × 10²).\n\nIf you want to set the value 499 for JPY currency transactions, where the number of decimal places is 0, you must set it to `4999` (4999.0 × 10^0 = 4999.0 × 1 - in other words, the value doesn't change.)\n\nThis field is **REQUIRED** for cumulative controls.\n", "example": 1000 }, "MaxTransactions": { "type": "integer", "minimum": 1, "format": "int64", "description": "Maximum number of transactions allowed. Once met or exceeded, subsequent transactions are declined by the evaluation control flow.\n", "example": 10 }, "ProcessingCodes": { "type": "array", "items": { "type": "string" }, "description": "Processing codes list for evaluating flex control conditions. If the value is empty, the flex control applies to any processing code.\n", "example": [ "07000", "07001" ] }, "ProgramFlexControlsResponse": { "type": "object", "description": "Paginated response containing flex controls grouped by program", "properties": { "pages": { "type": "integer", "description": "Total number of pages", "example": 5 }, "current_page": { "type": "integer", "description": "Current page number", "example": 1 }, "per_page": { "type": "integer", "description": "Number of programs per page", "example": 10 }, "total_items": { "type": "integer", "description": "Total number of programs", "example": 45 }, "programs": { "type": "array", "description": "List of programs with their flex controls", "items": { "$ref": "#/components/schemas/ProgramControlsItem" } } }, "required": [ "pages", "current_page", "per_page", "total_items", "programs" ] }, "ProgramControlsItem": { "type": "object", "description": "Flex controls for a single program", "properties": { "program_id": { "type": "integer", "format": "int64", "description": "Program ID", "example": 1234 }, "controls": { "$ref": "#/components/schemas/ProgramControls" } }, "required": [ "program_id", "controls" ] }, "ProgramControls": { "type": "object", "description": "Collection of restriction and accumulator controls", "properties": { "restriction_controls": { "type": "array", "description": "List of restriction controls", "items": { "$ref": "#/components/schemas/FlexControlRestrictionControl" } }, "accumulator_controls": { "type": "array", "description": "List of accumulator controls", "items": { "$ref": "#/components/schemas/FlexControlAccumulatorControl" } } }, "required": [ "restriction_controls", "accumulator_controls" ] }, "FlexControlRestrictionControl": { "type": "object", "description": "Simplified restriction control for program flex controls", "properties": { "name": { "type": "string", "description": "Control name", "example": "Single POS value card level limit" }, "type": { "type": "string", "description": "Control type", "example": "restriction" }, "level": { "type": "string", "description": "Control level (account or card)", "enum": [ "account", "card" ], "example": "card" }, "processing_codes": { "$ref": "#/components/schemas/ProcessingCodes" }, "conditions": { "type": "array", "description": "List of conditions", "items": { "$ref": "#/components/schemas/Condition" } }, "deny_code": { "type": "string", "description": "Deny code when control fails", "example": "Single_POS_Value" }, "active": { "type": "boolean", "description": "Is the control active?", "default": true, "example": true } }, "required": [ "name", "type", "level", "deny_code", "active" ] }, "FlexControlAccumulatorControl": { "type": "object", "description": "Simplified accumulator control for program flex controls", "properties": { "name": { "type": "string", "description": "Control name", "example": "Cumulative POS value card level limit" }, "type": { "type": "string", "description": "Control type", "example": "spending_limit" }, "level": { "type": "string", "description": "Control level (account or card)", "enum": [ "account", "card" ], "example": "account" }, "processing_codes": { "$ref": "#/components/schemas/ProcessingCodes" }, "max_limit": { "$ref": "#/components/schemas/MaxLimit" }, "max_amount": { "$ref": "#/components/schemas/MaxAmount" }, "max_transactions": { "$ref": "#/components/schemas/MaxTransactions" }, "limit_duration": { "$ref": "#/components/schemas/LimitDuration" }, "conditions": { "type": "array", "description": "List of conditions", "items": { "$ref": "#/components/schemas/Condition" } }, "deny_code": { "type": "string", "description": "Deny code when control fails", "example": "CUM_POS_Value" }, "active": { "type": "boolean", "description": "Is the control active?", "default": true, "example": true } }, "required": [ "name", "type", "level", "deny_code", "affect_target_account", "active" ] } }, "examples": { "ERUL0001": { "description": "Internal server error example.", "value": { "message": "internal server error", "error_code": "RULREP0500", "code": "ERUL0001" } }, "ERUL0101": { "description": "Error validating request header example", "value": { "message": "error validating request header", "error_code": "RULVAL0400", "details": [ { "location": "header.x-tenant", "message": "missing x-tenant" } ], "code": "ERUL0101" } }, "ERUL0102": { "description": "Error validating programId example", "value": { "message": "error validating request parameter", "error_code": "RULVAL0400", "details": [ { "location": "query.programId", "message": "programId must be a positive integer" } ], "code": "ERUL0102" } }, "ERUL0204": { "description": "Flex Controls not found for the specified program", "value": { "message": "Flex Controls not found for the specified program", "error_code": "RULREP0404", "code": "ERUL0204" } }, "ERUL1501": { "description": "Invalid pagination params example", "value": { "message": "error validating request parameters", "error_code": "RULVAL0400", "details": [ { "location": "query.page", "message": "page must be greater than or equal to 1" } ], "code": "ERUL1501" } } } }, "tags": [ { "name": "Program flex controls", "description": "API endpoints for retrieving flex controls grouped by program." } ], "paths": { "/v1/flex-controls": { "get": { "operationId": "get-v1-flex-controls", "summary": "List program flex controls", "description": "List all flex controls grouped by program, with pagination support.\nResults are ordered by program ID in ascending order.\n\nUse the optional `programId` query parameter to filter results to a single program.\nIf `programId` is provided and no templates are found for that program, a `404` is returned.\n\nIf no `programId` is specified and no templates exist at all, an empty paginated response is returned with status `200`.\n", "tags": [ "Program flex controls" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "x-tenant", "in": "header", "required": true, "description": "Organization ID / tenant identifier.", "schema": { "type": "string", "example": "org-12345" } }, { "name": "programId", "in": "query", "required": false, "description": "Filter flex controls by a specific program ID. Must be a positive integer greater than 0.", "schema": { "type": "integer", "format": "int64", "minimum": 1, "example": 123 } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination. Must be greater than or equal to 1. Defaults to 1 when omitted.", "schema": { "type": "integer", "minimum": 1, "default": 1, "example": 1 } }, { "name": "perPage", "in": "query", "required": false, "description": "Number of programs to return per page. Must be greater than or equal to 1. Defaults to 10 when omitted.", "schema": { "type": "integer", "minimum": 1, "default": 10, "example": 10 } } ], "responses": { "200": { "description": "OK. Returns paginated flex controls grouped by program.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProgramFlexControlsResponse" } } } }, "400": { "description": "Bad request. Returned in the following cases:\n- The `x-tenant` header is missing.\n- The `programId` query parameter is not a positive integer.\n- Pagination parameters are zero or cannot be parsed as integers.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "missing x-tenant header": { "$ref": "#/components/examples/ERUL0101" }, "invalid programId": { "$ref": "#/components/examples/ERUL0102" }, "invalid pagination params": { "$ref": "#/components/examples/ERUL1501" } } } } }, "404": { "description": "Not found. Returned when `programId` is specified but no flex controls are found for that program.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "template not found by programId": { "$ref": "#/components/examples/ERUL0204" } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "internal server error": { "$ref": "#/components/examples/ERUL0001" } } } } } } } } } } ```