The PRICE_TABLE strategy is a fee calculation method that generates installment plans with compound interest, fees, and Imposto sobre Operações Financeiras (IOF - Brazilian tax) calculations. This strategy automatically generates default transaction postings that are used by the transactions domain to create financial transactions. In this way, the PRICE_TABLE strategy removes the need to manually generate the transaction flow to see the transactions generated by the configured fees.

📘

The transaction mappings documented here represent the default behavior when using the PRICE_TABLE strategy. Any transaction flow different from these defaults must be created manually.

There are a few things you must be aware of when considering the use of the PRICE_TABLE strategy.

• IOF (Imposto sobre Operações Financeiras) is a Brazilian tax specific to financial operations.
• Maximum daily IOF calculation period is 365 days.
• All monetary values are rounded to 2 decimal places (HALF_EVEN).
• The strategy handles edge cases like negative interest on last installment through redistribution.
• Installment numbering starts at 1, not 0.

Client configuration

Clients (issuers/banks) configure the PRICE_TABLE strategy through DynamoDB fee models. This configuration determines how rates, taxes, and fees are calculated for transactions.

Configuration parameters

Interest rate configuration

The interestRate object supports fixed interest rates and rule-based interest rates.

Fixed interest rate:

{
  "type": "FIXED",
  "value": 12.0,
  "precedence": 0,
  "rules": null
}

Rule-based interest rate:

{
  "type": "RULE_BASED",
  "precedence": 0,
  "rules": [
    {
      "installments": { "from": 1, "to": 6 },
      "value": 10.0
    },
    {
      "installments": { "from": 7, "to": 12 },
      "value": 15.0
    }
  ]
}

Processing codes

The applyWhen.processingCodes array determines which transaction types trigger the PRICE_TABLE calculation. Common codes include:

• "01"—Domestic withdrawal
• "013100"—International withdrawal
• "00"—Purchase
• "003100"—International purchase

Configuration notes

• If interestRate.value is 0 or null, the strategy uses interest-free calculation.
• IOF rates are specific to Brazilian operations (for other countries, set to 0).
• precedence determines the order of fee application when multiple fees exist.
• applyInto specifies whether the fee applies to PRINCIPAL_AMOUNT or CONTRACT_AMOUNT.

Configuration to postings mapping

This table shows how DynamoDB configuration parameters map to the output postings generated by the PRICE_TABLE strategy.

Example mapping

Configuration:

{
  "interestRate": { "value": 12.0 },
  "fixedIofRate": 0.38,
  "dailyIofRate": 0.0082,
  "fixed": 10.0,
  "percentage": 2.5
}

Transaction: R$1,000.00 principal, 3 installments

Output postings (Installment 1):

{
  "amortization": 328.50,
  "interest_amount": 10.00,
  "iof_amount": 6.26,
  "daily_iof_amount": 2.46,
  "fixed_iof_amount": 3.80
}

Calculated fees (overall transaction):

{
  "feeAmount": 25.00,
  "interestAmount": 30.00,
  "iofAmount": 14.72
}

Key formulas

Calculation process

The PRICE_TABLE strategy follows these steps to calculate installments.

1—Days interval calculation

• Calculates the number of days between each installment due date.
• Accumulates days for IOF calculation, capped at 365 days maximum.
• Each installment tracks:
  • days—Days from previous installment
  • accumulatedDays—Cumulative days (max 365)

2—PMT (payment) calculation

• Uses compound interest formula to calculate fixed payment amount.
• Formula: PMT = principal × [r(1+r)^n] / [(1+r)^n - 1]
• Where:
  • r = monthly interest rate
  • n = number of installments
  • Adjusted for effective interval based on month length

3—Interest and amortization calculation

• For each installment:
  • Interest = remaining principal × ((1 + rate/100)^(days/30) - 1)
  • Amortization = PMT - interest
  • Remaining principal = previous remaining principal - amortization
• First installment uses actual days to first due date.
• Subsequent installments use effective month length (28-31 days).

4—IOF adjustment (principal recalculation)

• Recalculates principal to include IOF in amortization.
• Fixed IOF—Applied once (typically 0.38%).
• Daily IOF—Applied per accumulated day (typically 0.0082% per day, max 365 days).
• New principal accounts for both fixed and daily IOF.

5—IOF amount calculation

• **Daily IOF per installment **= amortization × (dailyIof/100) × accumulatedDays
• Fixed IOF = newPrincipal × (fixedIof/100) - added only to first installment

6—Negative interest redistribution

• If last installment has negative interest (due to rounding), redistributes it to previous installments.
• Redistribution ensures all interest amounts are non-negative.

7—Fee calculation

• Fixed Fee—Applied as defined.
• Percentage Fee—Applied as percentage of amount.
• Uses GREATER strategy (max of fixed or percentage).

Output - postings generated

The PRICE_TABLE strategy generates a postings map for each installment with the following fields:

Example posting output

postings: [
    amortization: 95.45,
    interest_amount: 4.55,
    iof_amount: 0.87,        // 0.38 (fixed) + 0.49 (daily) for installment 1
    daily_iof_amount: 0.49,
    fixed_iof_amount: 0.38
]

Note: The transactions domain consumes these postings keys (in snake_case) and converts them to camelCase for transaction generation.

Default transaction mappings

The following table shows the default transaction types generated by the transactions domain when processing PRICE_TABLE postings. These mappings are automatically applied based on processing codes and posting keys.

📘

Any transaction flow different from this table must be created manually by the client.

Interest-free scenario

When interestRate is 0 or null, the strategy uses the InterestFreeCalculator and the following conditions apply:

• Divides the amount equally across all installments
• No interest calculation
• No IOF recalculation (fixed and daily IOF remain 0)
• Only fees are applied (fixed/percentage)
• Postings will have:
  • amortization: amount / installmentsNumber
  • interest_amount: 0
  • iof_amount: 0
  • daily_iof_amount: 0
  • fixed_iof_amount: 0