Balances configurations overview

The Balances config API is a set of rules that informs the Pismo platform that impacts the ledger. Use the Balances config API to create and manage limits on account balances. Limiting account balances allows you to spend money appropriately and through different types of accounts. The Balances Config API indirectly impacts the limits and balances on the ledger by enabling settings that impact levels, filters, conditions, and results.

Understanding the structure

The hierarchy for balance configuration is: level > filter > condition > results.

  • The level defines which layer the configuration will be applied to and can be applied to an organization, program, or account. A level determines where the filters are applied.
  • Filters determine the criteria for a new scenario.
  • A scenario is one or more "conditions + results" configured for the filters.
  • Conditions define the requirements necessary to impact an account or limit.
  • Results provide the information the Pismo platform uses to impact the correct balance.

In the result object, the fields are consider, impact, amount, amount_consider, and reset_limit. For account-level configurations, the result objects can contain impact_account and counterpart_account. If the client does not use the consider field, the Pismo platform will use the same parameter in the impact field for the consider field.

The sum of the limits in the consider field determine which balances are used to allow the transaction and the impact field determines which balances are debited.

A balance is made of fields with certain values and when a balance is used, the values of the parameters are used. For example, if AvailableCreditLimitis in the consider field, the ledger will use the available_credit_limit, available_savings_account_limit, and total_overdraft_limit to allow the transaction. Reference the Considers types available diagram to understand which parameters make up which balances.

Example scenarios

In this example, an account has AvailableCreditLimit of 1,000 and OverLimit of 500.

  • The customer is making a purchase of 1,200.
  • Consider: AvailableCreditLimit & OverLimit
  • Impact: AvailableCreditLimit

Even though the account does not have a sufficient limit AvailableCreditLimit, the ledger will consider the sum of both limits AvailableCreditLimit & OverLimit to validate if the account has enough money in the balance. In this case, the sum of both balances is 1,500 and the purchase is 1,200. Since the AvailableCreditLimit is the only field to be impacted, the ledger will perform a debit only in the AvailableCreditLimit and the balance for the AvailableCreditLimit will be -200.

If the example did not include ‘OverLimit’ and AvailableCreditLimit is 1,000 and the purchase is 1,200, the purchase is rejected..

  • Consider: AvailableCreditLimit
  • Impact: AvailableCreditLimit

The results guide how the Pismo platform impacts the correct balance or limit.

The diagram contains the hierarchy of a balance configuraiton.

Setting up the Configs

Here are the main steps to set up the Configs and find an example after the tables:

  1. Define the Level
FeaturesOrgProgramAccount
Impact different balancesYesYesYes
Define the amount to impact balanceYesYesYes
Consider different balances/limitsYesYesYes
Define the amount to considerYesYesYes
Define when the limit will be resetedYesYesYes
Impact a related accountNoNoYes
Define a counterpart accountNoNoYes
  1. Choose the Filters
FieldDescription
Processing Code*Array of processing codes that must be considered
Number of InstallmentsSet the minimum and maximum number of installments
Merchant Category Code (MCC)Which categories of merchants fit into the scenario
Currency CodeWhich currencies impact different limits or accounts
Account TypeThe type of account that will impact another limit or account

*required fields

  1. Establish the Conditions
FieldDescription
Order*Order priority for conditions. The lower the number corresponds to the higher priority.

In practical terms, if you assign a lower order number to a condition, the lower order number condition will take precedence over conditions with higher order numbers.
Type*There are two types of conditions: default and custom. The custom conditions are used before the default condition.

Remember to choose the appropriate condition type based on your specific requirements.

custom:
The custom condition involves validating the available balance or limit. In the order to be applied, set up more custom conditions to validate there is a sufficient balance.

default:
The default condition is the final condition used in a list of custom conditions and should be created. If there are no custom conditions and only a default condition, the default condition is used. The default condition is not automatically created.
Amount to Check BalanceSpecifies which amount is used to determine if the customer has enough money. The amount can be the principal amount or installment amount. This field must be specified only when the indicated type is ‘custom’.

*required fields

  1. Setup the Results

Impact*: Array of balances or limits the ledger must check to perform a debit or a credit

BalanceDescriptionAccount type
Available Credit LimitBalance or limit available to the customerDebit or Credit
Available Total Installment CreditLimit available for installments in the accountDebit or Credit
Available Withdrawal CreditAvailable withdrawal limit specifically for the credit cardCredit
Available Savings Account LimitSavings balance available in the accountDebit
Additional Funds (NEW)Additional funds represent funds that can be used as supplementary when needed and are available to credit limit, held funds, or other funds.Debit
Held Funds (NEW)Funds held or blocked on the account.Debit

*required fields

Consider: Array of balances or limits the ledger must consider to check if it has an available limit.

BalanceDescriptionAccount type
Available Credit LimitBalance or limit available to the customer, including savings and overdraft limitDebit or Credit
Available Credit Limit & Overlimit**Balance or limit available to the customer, including overlimitCredit
Available Savings Account LimitAvailable limit of the savings accountDebit
Available Withdrawal CreditAmount available for withdrawal in the credit account.Credit
Available Total Installment CreditAmount available for installments in the credit account.Credit

**Overlimit must always be used with Available Credit Limit

Other result fields:

FieldDescription
Amount*Amount for crediting or debiting balances or limits on an account. You have several options for this field:

Principal Amount: The original amount, excluding any interest or fees.

Contract Amount: The final amount, including any interest and/or fees.

Installment Amount: The amount of each portion of an installment plan.
Amount ConsiderWhich amount must be considered to validate whether the account has sufficient limit or balance. You have several options for this field:

Principal Amount: The original amount, excluding any interest or fees.

Contract Amount: The final amount, including any interest and/or fees.

Installment Amount: The amount of each portion of an installment plan.
Reset LimitThe moment the limit needs to be reset. You have several options for this field:

Never: The limit referenced in the authorization is never reset.

Payment: The limit will reset when the client pays the credit card bill.

Last Installment: The limit resets only upon the final client installment payment.

*required fields

Other results fields that are only available for account-level configurations:

FieldDescription
Impact AccountRefers to a third account to which the credit or debit is applied.
Importantly, this impact account must be related to the principal account. For further details on related accounts, please refer to this documentation. In the impact_account object, there are two fields:

Account ID: The account_id that must be impacted. It must be related to the principal account.

Customer ID: Which customer_id of the above account_id the transaction is referring to.
Counterpart AccountRefers to the account to which the same amount for credit is applied. Importantly, this impact account must be related to the principal account. For further details on related accounts, please refer to this documentation. In the counterpart_account object, there are two fields:

Account ID: The account_id that must be impacted as a counterpart. It must be related to the principal account.

Processing Code:Which processing code should be used to impact the counterpart
{
  "level": "program",    level is being set
  "program_id": 999,
  "configs": [
    {
      "is_active": true,
      "filters": {     filter is being set
        "processing_codes": [
          "P01001",
          "P01005"
        ],
        "min_installments": 1,
        "max_installments": 5,
        "mcc": [],
        "account_type": "",
        "currency_code": ""
      },
      "scenarios": [
        {
          "condition": {   condition is being set
            "order": 1,
            "type": "default",
            "amount_to_check_balance": "amount"
          },
          "result": {
            "impact": [
              "AvailableCreditLimit"
            ],
            "consider": [
              "AvailableCreditLimit",
              "OverLimit"
            ],
            "amount": "contract_amount",
            "amount_consider": "principal_amount",
            "reset_limit": "payment"
          }
        },
        {
          "condition": {
            "order": 2,
            "type": "custom",
            "amount_to_check_balance": "installment_amount"
          },
          "result": {   result is being set
            "impact": [
              "AvailableTotalInstallmentCredit"
            ],
            "consider": [
              "AvailableTotalInstallmentCredit"
            ],
            "amount": "installment_amount",
            "amount_consider": "principal_amount",
            "reset_limit": "last_installment"
          }
        }
      ]
    },
    {
      "is_active": true,
      "filters": {
        "processing_codes": [
          "P01002",
          "P01007"
        ],
        "min_installments": 1,
        "max_installments": 5,
        "mcc": [],
        "account_type": "",
        "currency_code": ""
      },
      "scenarios": [
        {
          "condition": {
            "order": 1,
            "type": "default",
            "amount_to_check_balance": "amount"
          },
          "result": {
            "consider": [
              "AvailableCreditLimit",
              "OverLimit"
            ],
            "amount": "contract_amount",
            "amount_consider": "principal_amount",
            "reset_limit": "payment",
            "confirmation": {
              "impact": [
                "AvailableCreditLimit"
              ]
            }
          }
        },
        {
          "condition": {
            "order": 2,
            "type": "custom",
            "amount_to_check_balance": "installment_amount"
          },
          "result": {
            "consider": [
              "AvailableTotalInstallmentCredit"
            ],
            "amount": "installment_amount",
            "amount_consider": "principal_amount",
            "reset_limit": "last_installment",
            "confirmation": {
              "impact": [
                "AvailableTotalInstallmentCredit"
              ]
            }
          }
        }
      ]
    },
    {
      "is_active": true,
      "filters": {
        "processing_codes": [
          "P01020"
        ],
        "min_installments": 6,
        "max_installments": 29,
        "mcc": [],
        "account_type": "",
        "currency_code": ""
      },
      "scenarios": [
        {
          "condition": {
            "order": 1,
            "type": "custom",
            "amount_to_check_balance": "installment_amount"
          },
          "result": {
            "impact": [
              "AvailableTotalInstallmentCredit"
            ],
            "consider": [
              "AvailableTotalInstallmentCredit"
            ],
            "amount": "installment_amount",
            "amount_consider": "principal_amount",
            "reset_limit": "last_installment"
          }
        },
        {
          "condition": {
            "order": 2,
            "type": "default",
            "amount_to_check_balance": "amount"
          },
          "result": {
            "impact": [
              "AvailableCreditLimit"
            ],
            "consider": [
              "AvailableCreditLimit",
              "OverLimit"
            ],
            "amount": "contract_amount",
            "amount_consider": "principal_amount",
            "reset_limit": "payment"
          }
        }
      ]
    },
    {
      "is_active": true,
      "filters": {
        "processing_codes": [
          "P01007",
          "P01120"
        ],
        "min_installments": 6,
        "max_installments": 29,
        "mcc": [],
        "account_type": "",
        "currency_code": ""
      },
      "scenarios": [
        {
          "condition": {
            "order": 1,
            "type": "custom",
            "amount_to_check_balance": "installment_amount"
          },
          "result": {
            "consider": [
              "AvailableTotalInstallmentCredit"
            ],
            "amount": "installment_amount",
            "amount_consider": "principal_amount",
            "reset_limit": "last_installment",
            "confirmation": {
              "impact": [
                "AvailableTotalInstallmentCredit"
              ]
            }
          }
        },
        {
          "condition": {
            "order": 2,
            "type": "default",
            "amount_to_check_balance": "amount"
          },
          "result": {
            "consider": [
              "AvailableCreditLimit",
              "OverLimit"
            ],
            "amount": "contract_amount",
            "amount_consider": "principal_amount",
            "reset_limit": "payment",
            "confirmation": {
              "impact": [
                "AvailableCreditLimit"
              ]
            }
          }
        }
      ]
    }
  ]
}

Read more about account limit fields in Account limits.

The diagram contains the considers types available fields and the attributes that make up those fields.

Use Cases

Managing Credit Limits Based on Number of Installments

The Pismo platform provides the use case of a customized credit limit to your clients, such as for personal loans. In the following example, Pismo handles credit limit impacts based on the number of installments.

Scenario A - Authorizations up to 12 Installments:

  • Condition 1: If authorizations have up to 12 installments and there is sufficient available credit, Pismo impacts the AvailableCreditLimit.
  • Condition 2: If the available credit is insufficient, Pismo impacts the InstallmentCreditLimit.

Scenario B - Authorizations with more than 12 Installments:

  • Condition 1: For authorizations with more than 12 installments and if there is sufficient installment credit, Pismo directly impacts the InstallmentCreditLimit.
  • Condition 2: If the InstallmentCreditLimit is insufficient, Pismo impacts the AvailableCreditLimit.

In summary, to perform these configurations, create two distinct scenarios, each containing two specific conditions, as follows:

{
    "level": "program",
    "program_id":   1065,
    "configs": [
        {
            "filters": {
                "processing_codes": [
                    "00"
                ],
                "min_installments": 1,
                "max_installments": 12
            },
            "scenarios": [
                {
                    "condition": {
                        "order": 1,
                        "type": "custom",
                        "amount_to_check_balance": "amount"
                    },
                    "result": {
                        "impact": [
                            "AvailableCreditLimit"
                        ],
                        "consider": [
                            "AvailableCreditLimit",
                            "OverLimit"
                        ],
                        "amount": "contract_amount",
                        "amount_consider": "principal_amount",
                        "reset_limit": "payment"
                    }
                },
                {
                    "condition": {
                        "order": 2,
                        "type": "default"
                    },
                    "result": {
                        "impact": [
                            "AvailableTotalInstallmentCredit"
                        ],
                        "consider": [
                            "AvailableTotalInstallmentCredit"
                        ],
                        "amount": "contract_amount",
                        "amount_consider": "principal_amount",
                        "reset_limit": "payment"
                    }
                }
            ]
        },
        {        
            "filters": {
                "processing_codes": [
                    "00"
                ],
                "min_installments": 13,
                "max_installments": 99
            },
            "scenarios": [
                {
                    "condition": {
                        "order": 1,
                        "type": "custom",
                        "amount_to_check_balance": "amount"
                    },
                    "result": {
                        "impact": [
                            "AvailableTotalInstallmentCredit"
                        ],
                        "consider": [
                            "AvailableTotalInstallmentCredit"
                        ],
                        "amount": "contract_amount",
                        "amount_consider": "principal_amount",
                        "reset_limit": "payment"
                    }
                },
                {
                    "condition": {
                        "order": 2,
                        "type": "default"
                    },
                    "result": {
                        "impact": [
                            "AvailableCreditLimit"
                        ],
                        "consider": [
                            "AvailableCreditLimit",
                            "OverLimit"
                        ],
                        "amount": "contract_amount",
                        "amount_consider": "principal_amount",
                        "reset_limit": "payment"
                    }
                }
            ]
        }
    ]
}

Impact a related account according to the Processing Code and MCC

Appy when to selectively impact a sub account based on the merchant’s category, such as for multi-benefit cards or transport cards linked to credit cards. In the following example, the account that should be impacted is determined.

{
    "level": "account",
    "account_id": 12345678,
    "configs": [
        {
            "filters": {
                "processing_codes": [
                    "903002"
                ],
                "mcc":[
                    "4000"
                ]
            },
            "scenarios": [
                {
                    "condition": {
                        "order": 1,
                        "type": "default"
                    },
                    "result": {
                        "impact": [
                            "AvailableCreditLimit"
                        ],
                        "consider": [
                            "AvailableCreditLimit"
                        ],
                        "amount": "contract_amount",
                        "impact_account": {
                            "account_id": 34567890
                        }
                    }
                }
            ]
        }
    ]
}

Impacting different limits due to insufficient main limit

Use a different limit in situations where the main limit is not sufficient. With two distinct credit limits, the clean credit limit and the collateral credit limit, the Pismo platform determines which limit takes priority during the authorization flow. The example below shows which limit should be impacted.

{
    "level": "account",
    "account_id": 123456,
    "configs": [
        {
            "filters": {
                "processing_codes": [
                    "003100"
                ]
            },
            "scenarios": [
                {
                    "condition": {
                        "order": 1,
                        "type": "custom",
                        "amount_to_check_balance": "amount"
                    },
                    "result": {
                        "impact": [
                            "AvailableCreditLimit"
                        ],
                        "consider": [
                            "AvailableCreditLimit",
                            "OverLimit"
                        ],
                        "amount": "contract_amount"
                    }
                },
                {
                    "condition": {
                        "order": 2,
                        "type": "default"
                    },
                    "result": {
                        "impact": [
                            "InstallmentCreditLimit"
                        ],
                        "consider": [
                            "InstallmentCreditLimit"
                        ],
                        "amount": "contract_amount"
                    }
                }
            ]
        }
    ]
}