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.
Setting up the Configs
Here are the main steps to set up the Configs and find an example after the tables:
- Define the Level
| Features | Org | Program | Account |
|---|---|---|---|
| Impact different balances | Yes | Yes | Yes |
| Define the amount to impact balance | Yes | Yes | Yes |
| Consider different balances/limits | Yes | Yes | Yes |
| Define the amount to consider | Yes | Yes | Yes |
| Define when the limit will be reseted | Yes | Yes | Yes |
| Impact a related account | No | No | Yes |
| Define a counterpart account | No | No | Yes |
- Choose the Filters
| Field | Description |
|---|---|
| Processing Code* | Array of processing codes that must be considered |
| Number of Installments | Set the minimum and maximum number of installments |
| Merchant Category Code (MCC) | Which categories of merchants fit into the scenario |
| Currency Code | Which currencies impact different limits or accounts |
| Account Type | The type of account that will impact another limit or account |
*required fields
- Establish the Conditions
| Field | Description |
|---|---|
| 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 Balance | Specifies 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
- Setup the Results
Impact*: Array of balances or limits the ledger must check to perform a debit or a credit
| Balance | Description | Account type |
|---|---|---|
| Available Credit Limit | Balance or limit available to the customer | Debit or Credit |
| Available Total Installment Credit | Limit available for installments in the account | Debit or Credit |
| Available Withdrawal Credit | Available withdrawal limit specifically for the credit card | Credit |
| Available Savings Account Limit | Savings balance available in the account | Debit |
| 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.
| Balance | Description | Account type |
|---|---|---|
| Available Credit Limit | Balance or limit available to the customer, including savings and overdraft limit | Debit or Credit |
| Available Credit Limit & Overlimit** | Balance or limit available to the customer, including overlimit | Credit |
| Available Savings Account Limit | Available limit of the savings account | Debit |
| Available Withdrawal Credit | Amount available for withdrawal in the credit account. | Credit |
| Available Total Installment Credit | Amount available for installments in the credit account. | Credit |
**Overlimit must always be used with Available Credit Limit
Other result fields:
| Field | Description |
|---|---|
| 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 Consider | Which 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 Limit | The 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:
| Field | Description |
|---|---|
| Impact Account | Refers 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 Account | Refers 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.
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
InstallmentCreditLimitis insufficient, Pismo impacts theAvailableCreditLimit.
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"
}
}
]
}
]
}
Updated 5 months ago