PIpismo
Customer flex controls

Create customer flex control

Creates flex control for customer. You use flex controls to restrict financial operations. For example, you can set spending and usage limits. See Flexible transaction controls for more information.

To create a cumulative condition, set type to:

  • usage_limit: Cumulative flex control that increases by one until max_limit
  • spending_limit: Cumulative flex control that increases by the current transaction's amount until max_limit
  • cumulative_limit: Cumulative flex control that increases by one transaction or by transaction amount until a condition is met, applies only to flex controls with associated card_ids, and requires a reset_strategy

To create a restriction condition, set type as restriction.

Once you create the control, you can't change its type.

This endpoint generates a Customer flex control created event.

NOTE: This endpoint requires an account-specific access token.

post/v1/customers/{customerId}/flex-controls

Request

  • Base URL
    https://sandbox.pismolabs.io/rules
  • URL
    https://sandbox.pismolabs.io/rules/v1/customers/{customerId}/flex-controls
  • Auth
    HTTP bearer

Path parameters

customerIdnumber required
Example:9999999

Customer ID

Request body

type'spending_limit' | 'usage_limit' | 'restriction' | 'cumulative_limit' required

Flex control scope

  • usage_limit: Cumulative flex control that increases by one until max_limit
  • spending_limit: Cumulative flex control that increases by the current transaction's amount until max_limit
  • cumulative_limit: Cumulative flex control that increases by one transaction or by transaction amount until a condition is met, applies only to flex controls with associated card_ids, and requires a reset_strategy
  • restriction: Restriction flex control that only validates specified conditions
processing_codesstring[]

Processing codes list for evaluating flex control conditions. If the value is empty, the flex control applies to any processing code.

rule_reference_idstring

If rule_reference_id is set, this program-level flex control, if it exists, overrides this flex control.

namestring required

Flex control name

account_idinteger required

Account ID

currency_codestring

Flex control currency code (ISO 4217). Defines the precision used for monetary values such as max_limit, available_limit, and condition.value.

max_limitinteger

Defines the maximum limit for the control. Its meaning depends on the flex control type.

  • For spending_limit controls, max_limit represents the maximum spending amount allowed.
  • For usage_limit controls, max_limit represents the maximum number of transactions allowed.

Once met or exceeded, any subsequent transactions are declined by evaluation control flow.

For spending limits, note 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.

value = floatNumber × 10^X, where X is the number of digits after the decimal separator for the currency as defined in ISO 4217.

For 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²).

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

This field is REQUIRED for flex controls with the type of spending_limit and usage_limit, and it does not apply to flex controls with the type of restriction and cumulative_limit.

max_transactionsinteger

Maximum number of transactions allowed. Once met or exceeded, subsequent transactions are declined by the evaluation control flow. Valid only for flex controls with the type of cumulative_limit.

max_amountinteger

Maximum accumulated amount allowed. Once met or exceeded, subsequent transactions are declined by the evaluation control flow. Valid only for flex controls with the type of cumulative_limit. Note that the value must be calculated as follows.

value = floatNumber × 10^X, where X is the number of digits after the decimal separator for the currency defined in ISO 4217.

For 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²).

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

limit_durationstring

Flex control limit period duration (ISO 8601 format). For 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.

time_zonestring

IANA Time Zone database, such as "America/New_York". This 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. If time_zone is empty, the control is evaluated using the UTC time zone.

card_idsinteger[]

List of card IDs

activeboolean

If not specified, defaults to 'true'. If set to 'false', the flex control is skipped during evaluation.

deny_codestring

Deny code related to restriction. This code is returned when the evaluation does not meet the conditions.

response_codestring

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.

custom_codestring

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.

evaluation_orderinteger

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.

card_mode'credit' | 'debit'

Specifies the operational mode of the card.

Example request

{
  "processing_codes": [
    "07000",
    "07001"
  ],
  "rule_reference_id": "purchase-1M",
  "name": "Purchase 1M limit",
  "account_id": 500000,
  "currency_code": "BRL",
  "max_limit": 1000,
  "max_transactions": 10,
  "max_amount": 100000,
  "limit_duration": "P1M",
  "time_zone": "America/Sao_Paulo",
  "reset_period": {
    "week_day": "monday",
    "time": "3:00AM",
    "utc_time": "3:00AM"
  },
  "reset_strategy": {
    "reset_trigger": {
      "authentication_method": [
        "05"
      ]
    }
  },
  "conditions": [
    {
      "id": "b4930a4d-e2c4-4fdc-9803-c83dec3a30d1",
      "value": "10000"
    }
  ],
  "active": true,
  "deny_code": "ERR_VAL_BALANCE",
  "response_code": "57",
  "custom_code": "A1B",
  "card_mode": "credit"
}

Response

OK. Successful flex control creation.

idstring uuid required

Flex control ID is auto-generated at creation time.

type'spending_limit' | 'usage_limit' | 'restriction' | 'cumulative_limit' required

Flex control scope

  • usage_limit: Cumulative flex control that increases by one until max_limit
  • spending_limit: Cumulative flex control that increases by the current transaction's amount until max_limit
  • cumulative_limit: Cumulative flex control that increases by one transaction or by transaction amount until a condition is met, applies only to flex controls with associated card_ids, and requires a reset_strategy
  • restriction: Restriction flex control that only validates specified conditions
processing_codesstring[]

Processing codes list for evaluating flex control conditions. If the value is empty, the flex control applies to any processing code.

rule_reference_idstring

ID of program-level flex control. Only present in generic flex controls created for the entire program.

namestring

Flex control name

account_idinteger required

Account ID

customer_idinteger

Customer ID

card_idsnumber[]

Card ID list

currency_codestring

Flex control currency code (ISO 4217). Defines the precision used for monetary values such as max_limit, available_limit, and condition.value.

max_limitinteger

Defines the maximum limit for the control. Its meaning depends on the flex control type.

  • For spending_limit controls, max_limit represents the maximum spending amount allowed.
  • For usage_limit controls, max_limit represents the maximum number of transactions allowed.

Once met or exceeded, any subsequent transactions are declined by evaluation control flow.

For spending limits, note 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.

value = floatNumber × 10^X, where X is the number of digits after the decimal separator for the currency as defined in ISO 4217.

For 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²).

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

This field is REQUIRED for flex controls with the type of spending_limit and usage_limit, and it does not apply to flex controls with the type of restriction and cumulative_limit.

max_transactionsinteger

Maximum number of transactions allowed. Once met or exceeded, subsequent transactions are declined by the evaluation control flow. Valid only for flex controls with the type of cumulative_limit.

max_amountinteger

Maximum accumulated amount allowed. Once met or exceeded, subsequent transactions are declined by the evaluation control flow. Valid only for flex controls with the type of cumulative_limit. Note that the value must be calculated as follows.

value = floatNumber × 10^X, where X is the number of digits after the decimal separator for the currency defined in ISO 4217.

For 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²).

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

available_amountinteger

The remaining amount allowed for authorizations under the current flex control. This value decreases with each successful authorization and resets based on the defined reset strategy. Valid only for flex controls with the type of cumulative_limit.

available_transactionsinteger

The remaining number of transactions allowed for authorizations under the current flex control. This value decreases with each successful authorization and resets based on the defined reset strategy. Valid only for flex controls with the type of cumulative_limit.

limit_durationstring

Flex control limit period duration (ISO 8601 format). For 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.

reset_datetimestring date-time

The exact date and time of the next reset for the flex control's spending window, in RFC-3339 format. This value is response-only: it is calculated by the platform and is never accepted in requests.

When reset_period is defined, the reset follows the configured schedule (for example, month_day: 10 resets on the 10th day of every month). When reset_period is omitted, the reset occurs at the control's creation date and time plus limit_duration.

This value is recalculated whenever an authorization is evaluated. If no authorizations have been processed since the last reset, it may still point to a reset datetime that has already passed.

This field is returned only for flex controls with the type of spending_limit or usage_limit.

time_zonestring

IANA Time Zone database, such as "America/New_York". This 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. If time_zone is empty, the control is evaluated using the UTC time zone.

available_limitinteger

Represents the remaining limit for the flex control. Its meaning depends on the flex control type.

  • For spending_limit controls, available_limit is the remaining spending amount.
  • For usage_limit controls, available_limit is the remaining number of transactions allowed.

The available_limit is 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_period.

When available_limit is set in a PATCH request via Update account flex control or Update customer flex control, it resets current_spend_limit. In this case, available_limit cannot be greater than max_limit.

For spending limits, 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:

value = floatNumber * 10^x, where x is the number of digits for the currency as defined in ISO 4217.

For example, if you want to set the value 499.99 for BRL currency transactions, you must set 49999 = 499.99 * 10^2.

On the other hand, the Japanese money system doesn'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.)

activeboolean

If not specified, defaults to 'true'. If set to 'false', the flex control is skipped during evaluation.

deny_codestring

Deny code related to restriction. This code is returned when the evaluation does not meet the conditions.

response_codestring

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.

custom_codestring

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.

evaluation_orderinteger

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.

card_mode'credit' | 'debit'

Specifies the operational mode of the card.

customizedboolean

Indicates whether the flex control is updated at the account level or customer level (true) or managed at the program level (false).

To revert a customized flex control back to program-level management, call Update account flex control or Update customer flex control and set customized as false.

Example response

{
  "id": "89cbdadc-860b-4275-a5cd-d9d892fd3869",
  "processing_codes": [
    "07000",
    "07001"
  ],
  "rule_reference_id": "purchase-1M",
  "name": "Purchase 1M limit",
  "account_id": 8988000,
  "customer_id": 99999999,
  "card_ids": [
    11111,
    22222
  ],
  "currency_code": "BRL",
  "max_limit": 1000,
  "max_transactions": 10,
  "max_amount": 100000,
  "available_amount": 100000,
  "available_transactions": 10,
  "limit_duration": "P1M",
  "reset_datetime": "2022-03-08T21:19:55Z",
  "time_zone": "America/Sao_Paulo",
  "reset_period": {
    "week_day": "monday",
    "time": "3:00AM",
    "utc_time": "3:00AM"
  },
  "reset_strategy": {
    "reset_trigger": {
      "authentication_method": [
        "05"
      ]
    }
  },
  "available_limit": 300,
  "conditions": [
    {
      "attribute": "balance",
      "operator": "gt",
      "value": "10000"
    }
  ],
  "active": true,
  "deny_code": "ERR_VAL_BALANCE",
  "response_code": "57",
  "custom_code": "A1B",
  "card_mode": "credit",
  "customized": true
}

Changes

No recorded changes to this operation across all 1 revision of this API.