Understanding statements
Statements are the groups of balances that result from credit card transactions. This article explains how Pismo manages the different routines necessary to maintain a simple and reliable credit card balance management function.
You should have some understanding of the following:
- Network transactions - Statement balances are calculated according to transaction balances.
- Pismo core objects - All configurations for statements are at the program or account level. The different statuses at all levels of the hierarchy can change the behavior of statements applications.
Statement API endpoints
Statement API endpoints require an account-specific token, not a regular access token. Account tokens are embedded with an account ID.
Credit card cycles (billing periods)
Credit card contracts always carry a risk of default or delay in payments. To weather this risk, the Pismo platform manages credit card balances and interest accruals in cycles (billing periods). Every statement corresponds to a single cycle. When a cycle ends, another cycle begins. The relationship between transactions and statements can change, but the relationship between a statement and a cycle doesn’t change. This is because statements are ordered through their cycle number.
Every new account, upon creation, has a moving window of 30 cycles. Cycle numbers start at 1 and increment by 1 for each additional cycle. Every time a cycle is closed, a new one is created in the future, so each account always has 30 future cycles.
Calendars
To indicate the billing period that a cycle covers, every statement is paired with a group of dates. This is the calendar for the statement. A calendar includes the following:
- best transaction date -The first full day of a cycle. This always comes right after the last cycle closing date.
- cycle closing date - The last day of a cycle. On this date, after the cycle is closed, no more transactions are allowed in the statement. When a cycle closing date arrives, a grace period begins.
- due date - The date that the grace period ends. Note that all days of the grace period belong to the next cycle. Therefore, the due date marks the last day that the transaction balances in a statement can be paid off before charges start to accrue.
Calendar management
You can use the due date endpoints (and others in the same section) to manage statement calendars.
Balances
A statement summarizes transaction balances. The statement balance types are:
- previous balance
- debits
- credits
- current balance
- minimum payment
On the cycle closing date, the Pismo platform opens the next statement and uses the old statement's current balance as the previous balance for the next one. The debits and credits balances receive the sum of the amounts of the debit and credit transactions, respectively. A statement’s current balance should equal its previous balance, plus its debits, and less its credits. After the cycle closing date, the balances on a statement cannot be changed.
The Pismo platform updates the debits, credits and current balance values live for each new transaction as it occurs.
Cycle dynamics imply the possibility that a transaction occurs in one cycle, but nets out another transaction that happened in a different cycle. For example, a credit on Statement 2 could compensate for a debit on Statement 1.
The Pismo platform calculates a minimum payment for a statement at the cycle closing date. On this date, the platform assigns an open due date to the account, which equals the closed statement due date and marks the first day of debt in cases where an account goes into default.
Statement management
You can use the List statements endpoint (and others in the same section) to view account statements.
Accruals
The minimum payment determines whether the Pismo platform marks the debits as refinanced or overdue. If the payments made within the grace period are greater than or equal to the minimum payment but less than the previous balance, the debits are marked refinanced. If the payments made in the grace period are less than the minimum payment, the debits are marked as both refinanced and overdue. If the payments in the grace period are more than the previous balance`, the debits are marked paid.
One day after the due date, if the credits received are less than the previous balance, the account starts to accrue interest charges, penalties, and taxes. On the closing date, the Pismo platform posts these accruals as transactions and adds them to the total amount due. Note that accruals are posted on the statement being closed.
Revolving financial contracts charge tax and interest rates, so they generate the refinancing accrual type. The Pismo platform considers default rates and penalties to be overdue debt charges, so these generate the overdue accrual type. The rates can be set at a program or account level.
Each transaction has one accrued value for each accrual instance per day, per accrual type. All accruals are proportional to the debit balance due. This means that, if the customer makes a partial payment, the next accrual instance is generated based only on the remaining balance. Accruals are posted on the next cycle closing date.
Accrual management
You can manage accrued values for an account using the accrual endpoints. The accrual rates can be managed with the interest rate endpoints for programs and accounts.
Daily accrual routine
A scheduler triggers the daily accrual routine. The Pismo platform calculates accruals every day for all debit transactions that are overdue and that have a balance greater than zero. The routine runs through the following steps, by account, so multiple instances of the same application can run separately for different sets of accounts.
| Step | Description |
|---|---|
| Account lock key acquiring | Obtain the key to perform operations on a credit account. Each credit account can only receive operations from one routine at a time. |
| Accrual rate selection | The accrual rates can be selected on a program, account or contract level. Program rates are overwritten by account rates, and account rates are overwritten by contract rates. |
| Interest accrual | Calculates interest amounts for balances both before and after their due date. You can set different rates on a program or on an account level for refinancing and overdue accruals. |
| Default interest accrual | Calculates additional interest amounts for balances after their due date in case of default. You can set the rate on a program or account level. |
| Fine accrual | Calculates the fine for balances after their due date in case of default. You can set the fine on a program or account level. |
| Taxes accrual | Calculates the fixed and daily taxes applied to arrears. You can configure the fixed and the daily rate on a program level. |
| Account lock key return | Return the key to perform operations on the credit account. The key becomes available for other routines to manipulate the credit account. |
The routine selects only accounts that have debit transactions that are overdue and have a balance greater than zero. This means that the routine could run every day for each account.
Cycle closing routine
A scheduler triggers the cycle closing routine. This routine runs through the following steps for each account. Each step is part of the process that revolves cycles.
| Step | Description |
|---|---|
| Annual fee processing | The Pismo platform processes the annual fee into statements by cycle. Each annual fee's installment is registered as a scheduled transaction and won't affect the account limit until it is processed into the statement. You can configure the annual fee amount at the program level. |
| Foreign exchange adjustments | If you configure the program to settle foreign purchases on the cycle closing date (instead of on the transaction date), the Pismo platform processes the converted amount of the transaction into the statement. The platform converts the amount into the currency of the program, using the commercial rate of the cycle closing date. |
| Accrual transactions creation | The Pismo platform processes accrual registries into statements, grouped by their type (interest, default interest, or fine). |
| Tax transactions creation | The Pismo platform processes taxes accrual registries into statements. You can set this to happen on the cycle closing date or on the first day of each month. |
| Pending credit processing | The Pismo platform compensates any credit balance that wasn't discharged upon receipt with debit balances from the current statement. The platform manages balances on a transaction level, using a discharge routine that follows a payment hierarchy. |
| Minimum payment evaluation | The Pismo platform calculates the minimum payment value for each transaction category, sums the results, and posts the sum to the closing statement. You can set the categories on a program or account level. |
| Cycle closing | The Pismo platform closes the current cycle. When a cycle ends, the next one begins, so any transactions that happen on the cycle closing date, after the cycle closing routine, are registered in the new cycle, not the cycle that was just closed. |
| Cycle opening | The Pismo platform opens the next future statement, which becomes the current statement. The platform creates all new transactions in the current statement. For installment contracts, the platform creates the first installment on the current statement. |
| Debt opening date setting | The Pismo platform sets the open due date (which is the same as the due date) for the closed cycle's account. |
| Statement events messaging | The Pismo platform sends cycle closing, cycle opening, transaction creation, and discharge events. |
| New statement creation | The Pismo platform creates a new account statement. |
| New calendar creation | The Pismo platform creates a new account calendar. |
The cycle closing routine runs daily. The routine selects only accounts that have statements on their cycle closing date for processing. This means that, for each account, the routine runs once every cycle.
Reactive routines
The Pismo platform triggers reactive routines in response to events (usually a transaction creation or update). Each step is triggered separately. The following table describes the routines triggered in the statement management scope.
| Routine | Description |
|---|---|
| Payments and purchases processing | The Pismo platform recognizes credit or debit transactions created and, according to their transaction configuration, triggers internal routines. |
| Discharge | The Pismo platform receives credits and discharges them into previous debits. You can set up the charge order on the program level through transaction categories. You can also set up an inner charge order for each transaction type registered within each transaction category. See How the program uses configurable entities for more information. |
| Debt status normalization | The Pismo platform evaluates an account's debt status and, if the credits are more than the minimum payment, sets the account's collection status to Normal and its open due date to "Null". |
| Balance update | The Pismo platform adjusts debit, credit, and current balance values in the statement according to the new transaction amounts. |
| Accrual reversal | The Pismo platform identifies a credit received for a retroactive date and reverses any accrual that isn't due. Credits that represent a partial payment cause accruals to be reversed proportionally. For the case that credits are more than the minimum payment, all overdue accruals are reversed. |
Updated 3 months ago