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.
Fixed 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.

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

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

Configure accrual types at the program level by creating an accrual type rate entity. Open a service request.

In the service request, provide values for the following parameters:

transaction_category_id
accrual_type — The possible values are:
WITHDRAWAL_INTEREST
BILLPAYMENT_INTEREST
OVERDRAFT_INTEREST
FINANCIAL_TAX
period_to_calculate — When the accrual should be calculated. The possible values are UNTIL_DUE_DATE or AFTER_DUE_DATE.
default_rate — Rate used to calculate the accrual when the account is not overdue. Example: 2.00
rate_if_overdue — Rate used to calculate the accrual when the account is overdue. Example: 3.00
validity_to_calculate — When the rate is used to calculate the accrual. The possible values are:
IMMEDIATE — The rate is used to calculate the next generated accruals.
DUEDATE — The rate is used to calculate accruals only after the next due date.

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:

Fixed 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 fixed late payment fee, use the Pismo Control Center 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 fixed 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 fixed late payment fee, then the cardholder could be charged two late payment 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.

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

📘

Fixed late payment fees

🚧

Validation for configuring accruals

📘

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