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, the Pismo platform might apply a refinancing charge to the account for every day the balance remains unpaid. The account might accrue other charges during the cycle, such as interest on a withdrawal.

An accrual rate, which is usually a percentage, determines the charge amount. 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 account holder has not paid the total amount due
• Overdue—A daily charge applied to an unpaid balance if the account holder has not paid the minimum amount due (MAD)
• 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 the Pismo platform applies on the day an account becomes overdue
• Late payment fee—A fixed amount that the Pismo platform charges once per cycle whenever there are any overdue transactions. You configure this at the program level.

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

Refinancing accrual type rates

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 account is not overdue (that is, the cardholder has paid the MAD). The Pismo platform charges this accrual daily until the balance is zero (that is, until the TAD is paid). Example: 14.99 = 14.99%.
• overdue_rate_after_due_date—Revolving rate as a percentage if the cardholder is overdue (that is, the cardholder has not paid the MAD). The Pismo platform charges this accrual daily until you pay the MAD. If there is still an unpaid balance (that is, the TAD has not been met) after you've paid the MAD, the platform begins to use refinancing_rate_after_due_date. Example: 15.99 = 15.99%.

Overdue accrual type rates

Overdue accrual type rates only apply if the cardholder doesn't pay the minimum amount due. The PIsmo platform applies these rates in addition to the refinancing accrual type rates. Program 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. The Pismo platform charges this daily until you pay the MAD. Example: 1 = 1%.
• fine_rate—The rate for a fine that the Pismo platform charges on the day a transaction becomes overdue. The platform charges this only on the first overdue day for each transaction. The rate is a percentage. Example: 2 = 2%.

Late payment fees

Some markets might require you to charge the cardholder a fixed amount for an overdue account, regardless of how many transactions are overdue or their balances. For example, the charge could be $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. Alternatively, you can use Pismo Control Center to set the parameter. Once set, if an account has overdue transactions at the end of a credit cycle, the Pismo platform creates 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.

How to configure accrual types

You can configure accrual types at three levels.

• Program—Sets the default rates for all accounts and transactions within a program. This is the base configuration and is always required.
• Account—Overrides the program-level rates for a specific account.
• Transaction—Overrides both the program-level and account-level rates for a specific transaction. This is the most granular level and takes the highest priority.

Rate resolution hierarchy

When the Pismo platform calculates accruals for a transaction, it resolves the applicable rates using the following priorities.

The platform uses the program-level configuration as the base structure (accrual type, period to calculate, and additional configurations). Account-level and transaction-level rates only override the default_rate and rate_if_overdue values—they do not change the accrual type structure itself.

If multiple rates exist at the same level for the same accrual type, the most recently created rate takes precedence.

Transaction-level accrual type rates

Transaction-level accrual type rates allow you to set specific interest rates for an individual transaction. Use transaction-level rates when you need to apply a different interest rate to a specific transaction without affecting other transactions on the same account. Common scenarios include:

• Promotional rates for specific purchases or withdrawals
• Negotiated rates tied to a particular transaction
• Regulatory requirements that demand different rates per transaction

A transaction-level rate overrides the default_rate and rate_if_overdue for a single transaction. All other accrual properties (accrual type, period to calculate, additional configurations) continue to be inherited from the program-level accrual type rate.

Each transaction-level rate has a start_date and an optional end_date. The rate only applies when the processing date falls within this range. If end_date is not set, the rate has no expiration.

To create a transaction-level accrual type rate, open a service request and provide:

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 accrual rates or Configure account accrual 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 accrual rates to set default_rate to 2% for accruals of type REFINANCING for some program 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 the platform generates a transaction in this category for a REFINANCING accrual. If it generates the transaction before the due date, it uses the 2% rate from the first accrual type rate that you created. If it generates it after the due date, it uses the 3% rate from the second accrual type rate.

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 'month' refers to 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.

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 value for default_rate is 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 platform performs the same calculation to get the daily rates for overdue_rate_after_due_date and refinancing_rate_after_due_date.

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 <your_bearer_token>' \
     --header 'content-type: application/json' \
     --data '
{
  "credit": false,
  "posted_transaction": true,
  "transaction_type_id": 101,
  "description": "Purchase"
}
'

Step 2: Create a program 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 <your_bearer_token>' \
     --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 program 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 program 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 <your_bearer_token>' \
     --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 Create or update account transaction category 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 <your_bearer_token>' \
     --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 program 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 <your_bearer_token>' \
     --header 'content-type: application/json' \
     --data '
{
  "credit": false,
  "posted_transaction": true,
  "transaction_type_id": 102,
  "description": "Withdrawal"
}
'

Step 2: Create a program transaction category. Note that you pass the program ID 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 <your_bearer_token>' \
     --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 program transaction category ID. Assume the ID is 1237456.

Step 3: Open a service request to create a program-level accrual type rate. In the service request, provide the program ID and the program transaction category ID from Step 2. A program-level accraul type rate is required before you can set an overriding account-level accrual type rate.

Step 4: Use the Configure account accrual rates endpoint to create an account-level accrual type rate. This entity must link to the program transaction category created in Step 2, so you should pass the ID for that category 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 <your_bearer_token>' \
     --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"
}
'

Example 4: Creating an accrual type rate at the transaction level

The following steps demonstrate how to set a specific interest rate for an individual transaction.

Step 1: Create a program-level accrual type rate, if one does not already exist. (Refer to Examples 1 and 2).

Step 2: Open a service request to create a transaction-level accrual type rate. In the request, provide the ID of the target transaction, the transaction category accrual type ID from the program-level configuration, the desired default_rate and rate_if_overdue, and the start_date. Provide an end_date if you want the rate to expire.

Once created, the platform uses the transaction-level rate instead of the account-level or program-level rate when calculating accruals for that specific transaction.