--- 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. # Get customer flex control Get a flex control, given the `customerId` and `flexControlId`. NOTE: This endpoint requires an account-specific access token. # 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": { "Active": { "type": "boolean", "example": true, "default": true, "description": "If not specified, defaults to 'true'. If set to 'false', the flex control is skipped during evaluation." }, "AvailableLimit": { "type": "integer", "format": "int64", "description": "Total available limit to spend, calculated by: max_limit - current_spend_limit. The `current_spend_limit`, an internal field, is the total amount of all approved transactions in the `limit_duration` period. It is reset by the evaluation flow when a new transaction is evaluated in the new period according to the `reset_datetime`.\n\nWhen `available_limit` is set in a PATCH request, it resets `current_spend_limit`. In this case, `available_limit` cannot be greater than `max_limit`. Note that `available_limit` 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,\nwhere x is the number of digits for the currency as defined in ISO 4217.\n\nFor example, if you want to set the value 499.99 for BRL currency transactions, you must set 49999 = 499.99 * 10^2.\n\nOn the other hand, the Japanese money system does't use fractions of a yen (the Japanese currency). So, to set the value at 4999 yen, you must set 4999 = 4999.0 * 10^0 = 4999.0 * 1. (In other words, the value doesn't change.)\n", "example": 300 }, "CardMode": { "type": "string", "enum": [ "credit", "debit" ], "example": "credit", "description": "Specifies the operational mode of the card.\n" }, "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" ] }, "CurrencyCode": { "type": "string", "example": "BRL", "description": "Flex control currency code (ISO 4217)" }, "CustomCode": { "type": "string", "description": "Alphanumeric three-character custom code. This can be an alternative custom code. When the platform denies a control evaluation, it returns the custom code that provides the precise reason for the denial by the anti-fraud solution.\n", "minLength": 1, "maxLength": 3, "example": "A1B" }, "CustomerFlexControlsResponse": { "type": "object", "description": "Flex control response.", "properties": { "id": { "type": "string", "description": "Flex control ID is auto-generated at creation time.\n", "format": "uuid", "example": "89cbdadc-860b-4275-a5cd-d9d892fd3869" }, "type": { "$ref": "#/components/schemas/Type" }, "processing_codes": { "$ref": "#/components/schemas/ProcessingCodes" }, "rule_reference_id": { "type": "string", "example": "purchase-1M", "description": "ID of program-level flex control. Only present in generic flex controls created for the entire program." }, "name": { "$ref": "#/components/schemas/Name" }, "account_id": { "type": "integer", "example": 8988000, "format": "int64", "description": "Account ID" }, "customer_id": { "type": "integer", "format": "int64", "description": "Customer ID", "example": 99999999 }, "card_ids": { "type": "array", "description": "Card ID list", "items": { "type": "number", "format": "int64" }, "example": [ 11111, 22222 ] }, "currency_code": { "$ref": "#/components/schemas/CurrencyCode" }, "max_limit": { "$ref": "#/components/schemas/MaxLimit" }, "max_transactions": { "$ref": "#/components/schemas/MaxTransactions" }, "max_amount": { "$ref": "#/components/schemas/MaxAmount" }, "limit_duration": { "$ref": "#/components/schemas/LimitDuration" }, "reset_datetime": { "type": "string", "format": "date-time", "description": "Reset datetime (RFC-3339 format).\nIf `reset_datetime` is not set, by default it will calculated based on `limit_duration` period and the current time.\n", "example": "2022-03-08T21:19:55Z" }, "time_zone": { "$ref": "#/components/schemas/TimeZone" }, "reset_period": { "$ref": "#/components/schemas/ResetPeriod" }, "reset_strategy": { "$ref": "#/components/schemas/ResetStrategy" }, "available_limit": { "$ref": "#/components/schemas/AvailableLimit" }, "conditions": { "type": "array", "items": { "$ref": "#/components/schemas/Condition" }, "example": [ { "attribute": "balance", "operator": "gt", "value": "10000" } ] }, "active": { "$ref": "#/components/schemas/Active" }, "deny_code": { "$ref": "#/components/schemas/DenyCode" }, "response_code": { "$ref": "#/components/schemas/ResponseCode" }, "custom_code": { "$ref": "#/components/schemas/CustomCode" }, "evaluation_order": { "$ref": "#/components/schemas/EvaluationOrder" }, "card_mode": { "$ref": "#/components/schemas/CardMode" }, "customized": { "$ref": "#/components/schemas/Customized" } }, "required": [ "id", "type", "account_id" ] }, "Customized": { "type": "boolean", "example": true, "description": "Indicates whether the flex control is managed by the user. If `customized` is `false`, the flex control is managed by the card's program. Generally speaking, users shouldn't change flex controls created by the program, however it is possible to do so. You can reverse indivdually managing a flex control with a call to [Update account flex control](https://developers.pismo.io/pismo-docs/reference/patch-v1-accounts-flex-control) or [Update customer flex control](https://developers.pismo.io/pismo-docs/reference/patch-v1-customers-flex-control) and setting `customized` as `false`.\n" }, "DenyCode": { "type": "string", "description": "Deny code related to restriction.\nThis code is returned when the evaluation does not meet the conditions.\n", "example": "ERR_VAL_BALANCE" }, "ErrorDetail": { "type": "object", "description": "Error detail.", "properties": { "location": { "type": "string", "example": "payload.entity_type", "description": "Identifies where the request is causing an error." }, "message": { "type": "string", "description": "Description of error", "example": "`entity_type` should be `legal_person` or `natural_person`" } } }, "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" } } }, "ErrorResponseWithDetails": { "type": "object", "description": "Error response", "properties": { "message": { "type": "string", "description": "Error description" }, "details": { "type": "array", "description": "Provides more information about the error message.", "items": { "$ref": "#/components/schemas/ErrorDetail" } }, "error_code": { "type": "string", "description": "Error code ID", "deprecated": true }, "code": { "type": "string", "description": "Error code ID" } } }, "EvaluationOrder": { "type": "integer", "format": "int64", "description": "Order in which the control is evaluated. If this value is not provided, the control is evaluated after the controls with the configured `evaluation_order` value.\n", "minimum": 1, "maximum": 99 }, "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 }, "Name": { "type": "string", "description": "Flex control name", "example": "Purchase 1M limit" }, "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" ] }, "ResetPeriod": { "type": "object", "description": "Enables the specification of reset periods for accumulators based on the duration in `limit_duration`. When this field is set, it must follow the RFC 3339 pattern from ISO 8601. When `reset_period` changes, the `avaliable_limit` is reset.\n", "properties": { "month_day": { "type": "number", "description": "Month day to reset. Can only be used when `limit_duration` is monthly.", "minimum": 1, "maximum": 28 }, "month": { "type": "number", "description": "Numeric day of the month to reset the flex control. Can only be used when `limit_duration` is yearly.", "minimum": 1, "maximum": 12 }, "week_day": { "type": "string", "description": "Week day to reset. Can only be used when `limit_duration` is weekly.", "example": "monday", "enum": [ "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday" ] }, "time": { "type": "string", "description": "Time to reset flex control in time zone defined by control. Include only hours, minutes, and AM/PM. For example, `11:00PM` for 11PM or `00:00AM` for midnight. You can use `12` in hours as an alternative to `00` (for example,`12:59AM` is the same as `00:59AM`).\n", "example": "3:00AM" }, "utc_time": { "type": "string", "deprecated": true, "description": "*Note: This field has been deprecated, use `time` instead.*\nTime to reset the flex control in the UTC 0 time. Include only hours, minutes, and AM/PM. For example, `11:00PM` for 11PM or `00:00AM` for midnight. You can use `12` in hours as an alternative to `00` (for example,`12:59AM` is the same as `00:59AM`).\n", "example": "3:00AM" } } }, "ResetStrategy": { "type": "object", "description": "The strategy to reset the accumulators.", "properties": { "reset_trigger": { "type": "object", "description": "Trigger that resets the accumulators", "properties": { "is_password_present": { "type": "boolean", "description": "Indicates whether the client entered a password" }, "is_pin_validated_offline": { "type": "boolean", "description": "Indicates whether the pin was validated offline, triggering a reset of the accumulator when true" }, "authentication_method": { "type": "array", "description": "Indicates which authentication methods should trigger a reset of the flex-control accumulator.", "items": { "type": "string", "format": "text" }, "example": [ "password", "sms", "email" ] } } } } }, "ResponseCode": { "type": "string", "description": "Alphanumeric two-character response code. This can be the standard card network response code. When the platform denies a transaction, it returns the response code that provides the precise reason for the denial by the card network.\n", "minLength": 2, "maxLength": 2, "example": "57" }, "TimeZone": { "type": "string", "description": "IANA Time Zone database, such as \"America/New_York\".\nThis 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`.\nIf `time_zone` is empty, the control is evaluated using the UTC time zone.\n", "example": "America/Sao_Paulo" }, "Type": { "type": "string", "enum": [ "spending_limit", "usage_limit", "restriction", "cumulative_limit" ], "description": "Flex control scope\n * `usage_limit`: Accumulator flex control that increases by one until `max_limit`\n * `spending_limit`: Accumulator flex control that increases by the current transaction's `amount` until `max_limit`\n * `restriction`: Restriction flex control that only validates specified conditions\n * `cumulative_limit`: Accumulator flex control that increases by one until a condition is met, applies only to flex controls with associated `card_ids`, and requires a `reset_strategy`\n" } }, "examples": { "customerFlexControlResponse": { "description": "Create customer flex control example.", "value": { "id": "84ba9052-31d3-41da-99d2-a1632d5ce2e5", "type": "spending_limit", "rule_reference_id": "purchase-1M", "account_id": 50000001, "customer_id": 9999999, "name": "Purchase 1 Month credit card", "max_limit": 49999, "limit_duration": "P1M", "reset_datetime": "2022-03-08T21:19:55Z", "available_limit": 49999, "card_ids": [ 111111 ], "conditions": [ { "attribute": "balance", "operator": "gt", "value": "10000" } ], "active": true, "customized": true } }, "ERUL0002": { "description": "Operation not allowed example.", "value": { "message": "operation not allowed", "error_code": "RULVAL0403", "code": "ERUL0002" } }, "ERUL1203": { "description": "Error on repository example", "value": { "message": "Error on repository", "error_code": "RULREP0500", "code": "ERUL1203" } }, "ERUL1204": { "description": "Rules for customerID not found example", "value": { "message": "Rules for customerID not found", "error_code": "RULREP0404", "code": "ERUL1204" } }, "ERUL1205": { "description": "Customer spending limit rules not found example", "value": { "message": "Customer spending limit rules not found.", "error_code": "RULVAL0400", "code": "ERUL1205" } }, "ERUL1301": { "description": "Invalid request example", "value": { "message": "Invalid request", "error_code": "RULVAL0400", "details": [ { "location": "payload.limit_duration", "message": "`limit_duration` must follow ISO 8601 standard" } ], "code": "ERUL1301" } }, "ERUL1302": { "description": "Error validating request payload to GetCustomerSpendingLimitRule example", "value": { "message": "Error validating request payload to GetCustomerSpendingLimitRule", "error_code": "RULVAL0400", "details": [ { "location": "payload.limit_duration", "message": "`limit_duration` must follow ISO 8601 standard" } ], "code": "ERUL1302" } } } }, "tags": [ { "name": "Customer flex controls", "description": "API endpoints for managing customer flex controls." } ], "paths": { "/v1/customers/{customerId}/flex-controls/{flexControlId}": { "get": { "operationId": "get-v1-customers-flex-control", "summary": "Get customer flex control", "description": "Get a flex control, given the `customerId` and `flexControlId`.\n\nNOTE: This endpoint requires an account-specific access token.\n", "tags": [ "Customer flex controls" ], "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "customerId", "description": "Customer ID", "in": "path", "required": true, "schema": { "type": "number", "example": 9999999 } }, { "name": "flexControlId", "in": "path", "required": true, "description": "Flex control ID", "schema": { "type": "string", "format": "uuid", "example": "84ba9052-31d3-41da-99d2-a1632d5ce2e5" } } ], "responses": { "200": { "description": "OK. Flex control was found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerFlexControlsResponse" }, "examples": { "simple customer flex control": { "$ref": "#/components/examples/customerFlexControlResponse" } } } } }, "400": { "description": "Bad request. Validation error on request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponseWithDetails" }, "examples": { "Invalid request": { "$ref": "#/components/examples/ERUL1301" }, "Error validating request payload to GetCustomerSpendingLimitRule": { "$ref": "#/components/examples/ERUL1302" } } } } }, "403": { "description": "Forbidden. Authorization error on request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Operation not allowed": { "$ref": "#/components/examples/ERUL0002" } } } } }, "404": { "description": "Not found. Flex control for customerId not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Rules for customerID not found": { "$ref": "#/components/examples/ERUL1204" }, "Customer spending limit rules not found": { "$ref": "#/components/examples/ERUL1205" } } } } }, "500": { "description": "Internal server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Error on repository": { "$ref": "#/components/examples/ERUL1203" } } } } } } } } } } ```