An account can accrue various charges over the course of a credit cycle. For example, if an account has an unpaid balance at the end of the cycle, a refinancing charge might be applied to the account for every day the balance remains unpaid. Other charges might be accrued during the cycle, such as interest on a withdrawal.

The amount of a charge is determined by an accrual rate, which usually takes the form of a percentage. The Pismo platform uses entities called accrual types to configure accrual rates. Accrual types include:

Refinancing — A daily charge applied to an unpaid balance if the total amount due has not been paid.
Overdue — A daily charge applied to an unpaid balance if the minimum amount due has not been paid.
Withdrawal interest — Interest charged on a withdrawal.
Bill payment interest — Interest charged on a bill payment.
Overdraft interest — Interest charged on an overdraft.
Financial tax — A tax required by a particular country or region.
Fine — A one-time charge that's applied on the day an account becomes overdue.
Late payment fee — A fixed amount that is charged once per cycle whenever there are any overdue transactions. This is configured at the program level.

By default, accrual rates that are defined as percentages are monthly percentages. For example, if the refinancing accrual rate is set to 2%, this means 2% of the unpaid balance is accrued per month. You can change the interest rate period using a program parameter. Refer to Changing the interest rate period for more information.

📘
IOF rates (Brazil only) — You can set various rates for IOF taxes at the program level by configuring program parameters. Ror more information, refer to Program parameters reference table.

How to configure accrual types

Configure most accrual types using these structures:

Transaction category structure — Configure rates for the following accrual types:
- Refinancing
- Overdue
The rates are applied starting on the day after the statement due date. Use this structure to configure accrual types at the program or account level.
Accrual type rate structure — Extends transaction categories with rate structures that provide more flexibility. Use this structure to configure the following accrual types:
- Withdrawal interest
- Bill payment interest
- Overdraft interest
- Financial tax
You can configure these accruals to be applied either before or after the due date, and they can be configured at the program or account level.

Both structures require you to create and configure various entities. This is explained in detail in the following sections.

Transaction category structure

The Pismo platform defines two top-level entities for the transaction category structure:

Transaction category — Used to configure refinancing and overdue accrual types at the program level.
Account transaction category — Used to configure refinancing and overdue accrual types at the account level.

Refinancing accrual type rates only apply if the cardholder doesn’t pay the total amount due. Transaction categories and account transaction categories both contain the following fields for specifying refinancing accrual type rates:

refinancing_rate_after_due_date — Revolving rate as a percentage if the cardholder is not overdue (Example: 14.99 = 14.99%).
overdue_rate_after_due_date — Revolving rate as a percentage if the cardholder is overdue (Example: 15.99 = 15.99%).

Overdue accrual type rates only apply if the cardholder doesn't pay the minimum amount due. Transaction categories and account transaction categories both contain the following fields for specifying an overdue accrual type rate:

default_rate — Overdue rate as a percentage (Example: 1 = 1%)
fine_rate — The rate for a fine that is charged on the day a transaction becomes overdue. A fine is charged only on the first overdue day for each transaction.The rate is written as a percentage (example: 2 = 2%).

Configuring and managing rates at the program level

Configure these rates at the program level by creating a transaction category. To create and manage transaction categories, use these endpoints:

After you create a transaction category, use create a program transaction type to link it to a transaction type. One transaction category can be linked to multiple transaction types. See How the program uses configurable entities for more information.

Configuring and managing rates at the account level

To configure rates at the account level, first configure them at the program level. Next, use the Save account interest rate endpoint to create an account transaction category for the account in question and link it to the transaction category. This endpoint enables you to configure rates for the account transaction category. These rates override the rates configured in the transaction category for the specified account.

Use List account interest rates to view the rates set in an account transaction category. Use Cancel account transaction category to delete an account transaction category.

Accrual type rate structure

Configure the following accrual types using the accrual type rate structure:

Withdrawal interest
Bill payment interest
Overdraft interest
Financial tax

Configuring accrual types at the program level

Use the Configure program interest rates endpoint to configure accrual types at the program level. The following code sample shows an example payload for configuring annual rates at the program level.

curl --request POST  
     --url <https://sandbox.pismolabs.io/credit-cycle-configurations/v1/programs/5689/accrual-type-rates>  
     --header 'accept: application/json'  
     --header 'authorization: Bearer eyJhbG...'  
     --header 'content-type: application/json'  
     --data '  
{  
  "accrual_type": "WITHDRAWAL_INTEREST",  
  "period_to_calculate": "UNTIL_DUE_DATE",  
  "validity_to_calculate": "IMMEDIATE",  
  "transaction_category_id": 1237456,  
  "default_rate": 2,  
  "rate_if_overdue": 3  
}

Configuring and managing accrual types at the account level

To configure accrual types at the account level, first configure them at the program level. After that, use the Configure interest rates at account level endpoint to configure the accrual type at the account level, passing an account ID and transaction category ID as parameters.

📘
You can't create an account accrual type rate without first creating the corresponding accrual type rate. Even though you don't pass in the ID of the accrual type rate when you create an account accrual type rate, the Pismo platform is able to use the transaction_category_id, accrual_type and period_to_calculate fields to determine which of the program rates to override with the account-specific rate.

Use the following endpoints to list and delete account accrual type rates:

Late payment fees

Some markets might require you to charge the cardholder a fixed amount for being overdue, regardless of how many transactions are overdue or their balances. For example, a cardholder might be charged $20 at the end of a credit cycle if any transactions are overdue.

To set a late payment fee, use Create program parameter or Update program parameter to set the LATE_PAYMENT_FEE program parameter to the value of the fee. Once this parameter is set, if an account has overdue transactions at the end of a credit cycle, the Pismo platform uses the Force operation endpoint to create a debit transaction on the account for the amount of the fixed fee.

The late payment fee is not linked to any particular transaction category. Any overdue balance for the program triggers it.

🚧
Note that if you configure both the fine rate for a transaction category and a late payment fee, then the cardholder could be charged two late fees for the same overdue transaction.

Validation for configuring accruals

By default, when you update an accrual rate, the Pismo platform starts applying the new rate immediately. In some cases, you might want the platform to wait until the next cycle due date to start applying the new rate. To do this, use Configure program interest rates or Configure account interest rates to set the validity-to-calculate field to DUE_DATE (at the program or account level, respectively).

For example, suppose you use Configure program interest rates to set default_rate to 2% for accruals of type REFINANCING for some transaction category, and you set validity_to_calculate to IMMEDIATE. This creates a new accrual type rate. Later, you use the same endpoint to set default_rate to 3% for REFINANCING accruals for the same transaction category, but this time, you set validity_to_calculate to DUE_DATE. This creates another new accrual type rate.

Now, suppose a transaction is created in this category for a REFINANCING accrual. If it’s created before the due date, it uses the 2% rate from the first accrual type rate that you created. If it’s created after the due date, it uses the 3% rate from the second accrual type rate.

📘
Note that this example only works if you set the rate at the program level using Configure program interest rates. To set a rate at the account level, you need to use Configure account interest rates. This endpoint only has options for configuring WITHDRAWAL_INTEREST, BILLPAYMENT_INTEREST, and OVERDRAFT_INTEREST. It's possible to set REFINANCING, OVERDUE and FINE using the accrual type rate structure (which would enable you to set validity-to-calculate to DUE_DATE for them). To do this, open a service request.

Changing the interest rate period

By default, accrual rates are monthly rates. For example, if you set the refinancing rate to 10%, you’re setting the rate to 10% per month, where a month is defined as a business month, which is 30 days. On the other hand, if you want to use annual rates, you should set the interest rate period to 365 days (a calendar year). To do this, use the Pismo Control Center to set the program parameter Interest rate period to 365.

No matter how you set the period, the Pismo platform converts the rates into daily rates to apply them. The platform divides each configured rate by Interest rate period to get the corresponding daily rate.

🚧
IMPORTANT: When you change Interest rate period, it changes the accrual calculations for ALL interest rates in the program (except fine_rate, which is not affected by Interest rate period). If you already have existing rates operating, you must change them within the same day to avoid financial issues. To find the new value for an existing rate when changing Interest rate period, use this formula.
New value for existing rate = New Interest rate period / old Interest rate period x old value of existing rate
Here's an example of changing an existing monthly rate (Interest rate period = 30) to an annual rate.
New Interest rate period = 365
Existing rate (monthly): 15%
New value for existing rate (annual) = New Interest rate period / old Interest rate period x old value of existing rate = 365/30 x 15% = 182.5%

For example, to use annual rates based on a calendar year, you would configure the rates in the usual way, providing the nominal interest rates for one year. Then, you would set Interest rate period to 365. The following code sample shows a sample payload for configuring annual rates by program.

curl --request POST \
--url https://api-sandbox.pismolabs.io/statements-v2/v1/transactions-categories \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-program-id: 1122' \
--data '
{
"default_rate": 178,
"fine_rate": 2,
"overdue_rate_after_due_date": 178,
"refinancing_rate_after_due_date": 178,
"description": "purchase",
"charge_order": 2,
"secondary_charge_order": 7
}

In the sample, the default_rate field is set to 178, meaning a 178% annual accrual rate. The platform divides 178 by 365 to get a corresponding daily rate of 0.48767123%. (The Pismo platform rounds the result to 8 decimal places.) The same calculation is done to get the daily rates for overdue_rate_after_due_date and refinancing_rate_after_due_date.

🚧
Note that the fine_rate field in the sample code is set to only 2%. Because fine_rate is applied only once on the first day the account becomes overdue, the platform ignores Interest rate period and treats fine_rate as a monthly rate.

📘
Changing Interest rate period affects all accrual rates at both program and account level (except for fine_rate, as noted above.)

Examples

Example 1: Configuring refinancing and overdue accrual types at the program level

The following steps demonstrate how to configure rates for refinancing and overdue accrual types at the program level.

Step 1: Create a debit transaction type:

curl --request POST \
     --url https://api-sandbox.pismolabs.io/transactions-core/v1/transaction-types \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbG...' \
     --header 'content-type: application/json' \
     --data '
{
  "credit": false,
  "posted_transaction": true,
  "transaction_type_id": 101,
  "description": "Purchase"
}
'

Step 2: Create a transaction category. Note that the program ID is passed as a header. This must be the program that the account is in.

curl --request POST \
     --url https://api-sandbox.pismolabs.io/statements-v2/v1/transactions-categories \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbG...' \
     --header 'content-type: application/json' \
     --header 'x-program-id: 5689' \
     --data '
{
  "description": "Rate settings",
  "refinancing_rate_after_due_date": 15.99,
  "default_rate": 1.99,
  "fine_rate": 2.95,
  "overdue_rate_after_due_date": 17.99,
  "minimum_value": 1,
  "charge_order": 2
}
'

If successful, the request returns a transaction category ID. Assume the ID is 1237456.

Step 3: Use the Create program transaction type endpoint to create a program transaction type linking the category to the transaction type. This time, the program ID is passed as a path parameter. Creating this link results in the rates defined in the transaction category being applied to any transactions that have the specified transaction type.

curl --request POST \
     --url https://sandbox.pismolabs.io/credit-cycle-configurations/v1/programs/5689/program-transaction-types \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbG...' \
     --header 'content-type: application/json' \
     --data '
{
  "transaction_type_id": 101,
  "transaction_category_id": 1237456,
  "charge_order": 2
}
'

Example 2: Configuring refinancing and overdue accrual types at the account level

The following steps demonstrate how to configure rates for refinancing and overdue accrual types at the account level.

Steps 1 and 2: The same as steps 1 and 2 in Example 1.

Step 3: Use the Save account interest rate endpoint to create an account transaction category for the account. You set the rates for the new category in the same request.

curl --request POST \
     --url https://api-sandbox.pismolabs.io/statements-v2/v1/accounts/129006785/accounts-transactions-categories \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbG...' \
     --header 'content-type: application/json'
     --data '
{
  "description": "purchase",
  "refinancing_rate_after_due_date": 15.99,
  "default_rate": 1,
  "fine_rate": 2,
  "overdue_rate_after_due_date": 17.99,
  "refinancing_rate_after_due_date_multiplier_percent": 1.5,
  "default_rate_multiplier_percent": 1.7,
  "fine_rate_multiplier_percent": 2,
  "overdue_rate_after_due_date_multiplier_percent": 0.7,
  "start_cycle": 4,
  "start_date": "2021-08-20"
}
'

These rates override the rates in the transaction category.

Example 3: Configuring a withdrawal interest accrual type at the account level

The following steps demonstrate how to configure a withdrawal interest accrual type at the account level.

Step 1: Create a debit transaction type for a withdrawal:

curl --request POST \
     --url https://api-sandbox.pismolabs.io/transactions-core/v1/transaction-types \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbG...' \
     --header 'content-type: application/json' \
     --data '
{
  "credit": false,
  "posted_transaction": true,
  "transaction_type_id": 102,
  "description": "Withdrawal"
}
'

Step 2: Create a transaction category. Note that the program ID is passed as a header. This must be the program that the account is in.

curl --request POST \
     --url https://api-sandbox.pismolabs.io/statements-v2/v1/transactions-categories \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbG...' \
     --header 'content-type: application/json' \
     --header 'x-program-id: 5689' \
     --data '
{
  "description": "Rate settings",
  "refinancing_rate_after_due_date": 15.99,
  "default_rate": 1.99,
  "fine_rate": 2.95,
  "overdue_rate_after_due_date": 17.99,
  "minimum_value": 1,
  "charge_order": 2
}
'

If successful, the request returns a transaction category ID. Assume the ID is 1237456.

Step 3: Open a service request to create an accrual type rate. In the service request, provide the program ID and the transaction category ID from step 2.

Step 4: Use the Configure interest rates at account level endpoint to create an account accrual type rate. This entity must be linked to the transaction category created in Step 2, so the ID for that category is passed in transaction_category_id.

curl --request POST \
--url https://api-sandbox.pismolabs.io/statements-v2/v1/accounts/129006785/accrual-types-rates \
     --header 'accept: application/json' \
     --header 'authorization: Bearer eyJhbG...' \
     --header 'content-type: application/json' \
     --header 'x-program-id: 1122' \
     --data '
{
  "transaction_category_id": 1237456,
  "accrual_type": "WITHDRAWAL_INTEREST",
  "period_to_calculate": "UNTIL_DUE_DATE",
  "default_rate": 2.99,
  "rate_if_overdue": 18.5,
  "validity_to_calculate": "IMMEDIATE"
}
'

Configuring accrual rates

📘

How to configure accrual types

Transaction category structure

Configuring and managing rates at the program level

Configuring and managing rates at the account level

Accrual type rate structure

Configuring accrual types at the program level

Configuring and managing accrual types at the account level

📘

Late payment fees

🚧

Validation for configuring accruals

📘

Changing the interest rate period

🚧

🚧

📘

Examples

Example 1: Configuring refinancing and overdue accrual types at the program level

Example 2: Configuring refinancing and overdue accrual types at the account level

Example 3: Configuring a withdrawal interest accrual type at the account level

Changelog

Support

Pismo is here to help