Loan Module - Request

The fields of the Data object supported by a Loan module request are defined in alphabetical order below:

🟥 Data

The Data object encapsulates the request data for a given module, and must always be provided.

Fields: 🔹Country

Objects: 🟥 AccrualConfigs[], 🟥 Advances[], 🟦 Apr, 🟦 ARM, 🟦 BalAdjs[], 🟦 BusinessRules, 🟦 Capitalize[], 🟦 Construction, 🟦 EditOutput, 🟦 EndBal, 🟦 Fees[], 🟦 Format, 🟦 Holidays[], 🟦 MI, 🟦 ODI, 🟦 PmtStreams, 🟦 Protection, 🟦 TILARESPA2015

🔹 Data.Country

This field allows the calling application to specify a two (2) character or three (3) digit country code. If none is provided, then a default value of US will be used. Please see the Countries Appendix for the list of supported countries and their associated codes.

Specifying the Country will also set the default value for the Apr.Code and Format.CurrencyDecimals fields, as appropriate for the country specified.

🟥 Data.AccrualConfigs[]

This array of AccrualConfig objects must have at least one member, and is used to specify how interest is calculated.

Fields: 🔸AccrualCode, 🔹Capitalize, 🔹Date, 🔹ExtraDays, 🔹IntRate, 🔹IntRound, 🔹NewPmt, 🔹PmtRound

Objects: 🟦 Tiers[]

🔹 Data.AccrualConfigs[].AccrualCode

The method of interest accrual is defined by this field. A value of default means one of two things: if no accrual method has beend defined at all, use the system default of 201. If an accrual code has been previously defined, then the SCE will continue to use that method. Please see the following table of accrual codes and their descriptions for the meanings of each code.

Add-on interest methods [401...406] have restrictions that apply. Only equal payment loans with one AccrualConfig object may use add-on interest. In addition, construction loans may not be used with add-on interest. Also, any protection products requested must also be single premium.

🔹 Data.AccrualConfigs[].Capitalize

If interest due is to be added to principal (capitalized) on the specified Date, then set this field's value to true.

🔹 Data.AccrualConfigs[].Date

Set the date of this event. If the Date field is not specified, then it will default to the earliest specified Advance.Date.

All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, to change the interest rate on January 2, 2021, the field would be specified as "Date" : "2021-01-02".

However, to provide power and flexibility to the calling application, the SCE will also understand Date values in the following formats:

• NNNN-00-00 If you wish to change an interest accrual parameter on the date of a specific payment number (NNNN), use a value of NNNN-00-00. Thus, an value of 0012-00-00 instructs the SCE to set the date of this event equal to that of the 12^th payment. A vale of 0000-00-00 will set the date of the event equal to the date of the first advance.

🔹 Data.AccrualConfigs[].ExtraDays

Increase or decrease the number of days between this event and the next event by the value of this field. e.g. 1 will be considered one more day of interest.

🔹 Data.AccrualConfigs[].IntRate

Defines the annual interest rate that applies at and beyond this event. If no IntRate is specified, the previously defined interest rate is used. A value of zero (0) will be used if no previous IntRate has been defined.

🔹 Data.AccrualConfigs[].IntRound

Defines how interest is to be rounded.

🔹 Data.AccrualConfigs[].NewPmt

If the payment should change to reflect a new interest rate, set the value of this field to true; otherwise, the payment will not change after this event. If only one AccrualConfig object is being specified, then this field should be omitted altogether.

🔹 Data.AccrualConfigs[].PmtRound

How are calculated payments to be rounded at and beyond this event? best means to choose the payment that returns a minimal ending balance at the end of amortization. If two payments result in the same minimal error magnitude, the smaller payment is chosen.

Note: If the BusinessRules.ZeroInterestRule field is set to 'true' and all interest rates are zero, payments are required to be rounded down. This rule ensures the total of payments never exceeds the amounts of the loan to pay off (principal balance).

🟦 Data.AccrualConfigs[].Tiers[]

To compute interest using a split rate method, where different rates are applied to different parts of the balance, the calling application will need to specify a Tier object with its associated Rate and Ceiling fields. Note that the interest rate which is used above the final Ceiling is the one specified in the AccrualConfig object. Furthermore, the Rate objects must be ordered in ascending order based upon the Ceiling amount.

As en example, assume that the calling application needs to charge 20% on the first $100, 15% up to $250, and 10% for the remaining balance. The AccrualConfig object needed to implement this split rate structure is:

"AccrualConfigs" : [
  {
  "AccrualCode" : "201",
  "Date" : "2020-04-01",
  "IntRate" : "10.000",
  "Tiers" : [
    { "Rate" : "20.0", "Ceiling" : "100.00"},
    { "Rate" : "15.0", "Ceiling" : "250.00"}
  ]
  }
]

Fields: 🔸Ceiling, 🔸Rate

Objects: None

🔸 Data.AccrualConfigs[].Tiers[].Ceiling

Defines the upper bound to which the specified split rate tier will apply.

🔸 Data.AccrualConfigs[].Tiers[].Rate

Defines the interest rate that applies to this split rate tier.

🟥 Data.Advances[]

The array of Advance objects is used to specify the cash advances made to the borrower and must have at least one member.

Fields: 🔹Amount, 🔹Compute, 🔸Date, 🔹ExtraDays, 🔹NewPmt, 🔹Position

Objects: None

🔹 Data.Advances[].Amount

The proceeds to be advanced to the borrower is defined using this field. If the calling application requests that the advance be computed (see the Advance.Compute field below), then the value of this field (if present) will be added to the computed advance amount, which can be useful in multiple advance loans.

🔹 Data.Advances[].Compute

Some applications like to provide useful "what if?" calculations, such as "how much can I afford to borrow given a specified loan term, interest rate, and payment stream?" Here at J. L. Sherman and Associates, we call this a "Roll to Advance" calculation.

If the value of this field is true, then the calling application is requesting that the SCE calculate one or more advances given a specified term, interest rate, and payment stream. With this in mind, all PmtStream objects (which define the specified payment streams in the loan) may not have a PmtType of CalcPmt. Usually, all payment streams will be defined using a PmtType of FixedPmt.

🔸 Data.Advances[].Date

This field's value holds the date on which the advance is made. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, an advance date of January 2, 2021 would be specified as "Date" : "2021-01-02".

🔹 Data.Advances[].ExtraDays

Increase or decrease the number of days between this event and the next event by the value of this field. e.g. 1 will be considered one more day of interest.

🔹 Data.Advances[].NewPmt

If the payment should change to reflect a new advance, set the value of this field to true; otherwise, the payment will not change after this event. If only one Advance object is being used, then this field should be omitted altogether.

🔹 Data.Advances[].Position

If an advance and a payment fall on the same day, the value of this field determines which event occurs first in the amortization schedule. Note that the first advance of every loan is required to occur before the first scheduled payment.

• BeforePmt means that when the advance occurs on the same date as a payment, the advance is amortized before the payment.
• AfterPmt means that when the advance occurs on the same date as a payment, the payment is amortized before the advance.

🟦 Data.Apr

Settings related to the computed effective rate returned by the SCE (most commonly, the Regulation Z APR in the United States of America) are contained in the fields of this object.

Fields: 🔹Code, 🔹Decimals, 🔹Max, 🔹MAPR_Max, 🔹SinglePayFraction, 🔹StrictTime, 🔹UseMAPR

Objects: None

🔹 Data.Apr.Code

The method of APR computation is defined by this field. If this field is not included, the default method depends upon the value of the Country field. For the United States of America, the default value is 100 (Actuarial). For a country in the European Union, the default value is 50 (European Union APR). For Canada, the default value is 60.

🔹 Data.Apr.Decimals

The number of decimal places of accuracy for the disclosed APR is determined by this field. The default value of this field is 3.

🔹 Data.Apr.Max

If the calling application wants the SCE to check the computed APR against a specified maximum APR, then specify the maximum APR using this field. If a maximum is specified, then this maximum will be included in the APR response object in the Max field, and a MaxExceeded field will also be returned to inform the calling application whether or not the specified maximum was exceeded.

🔹 Data.Apr.MAPR_Max

If you are computing the Military APR (see UseMAPR below) and wish to override the default maximum APR value of 36%, then specify the desired maximum as the value of this field.

🔹 Data.Apr.SinglePayFraction

This field only applies to single advance, single payment transactions of term less than one year. For these loans, when the term of the loan is a number of months, Appendix J allows for the term of the loan to be expressed as either a number of months over twelve, or the number of actual 24-hour days in the loan over 365. For the former, use InMonths. For the latter, use InDays.

🔹 Data.Apr.StrictTime

When monthly payments are intended for the 29th or 30th of the month, how should the number of unit periods and fraction be calculated in February, when the day of the payment cannot be the intended day? (e.g. A non-leap year February where payments are meant for the 29th, but end up on the 28th). The StrictTime field acknowledges and disambiguates the calculation. Regular payments generally hold the fraction of a unit period constant, based on the date of the first payment. The SCE allows for a constant fraction of a unit period or a strict time accounting, acknowledging that in February, the fraction of a unit period changes.

When the value of this field is true, the SCE will calculate the fraction of a unit period strictly according to the rules of Appendix J of Regulation Z.

A value of false instructs the SCE to keep the fraction of a unit period constant, equal to the fraction obtained by the time calculated from the date of the first payment to the transaction date.

🔹 Data.Apr.UseMAPR

If this field is set to a value of true, then the SCE will compute the Military APR in addition to the Regulation Z APR. The MAPR object will be included in the loan response.

🟦 Data.ARM

The existance of this optional object alerts the Loan module to use adjustable rate mortgage rules. If the loan is not an ARM loan, do not include this field. The existence of this field toggles the rules explained below.

Fields: 🔹CalcType

Objects: 🟥 FullyIndexedRate, 🟥 Limits, 🟦 PostTeaser, 🟥 Teaser

🔹 Data.ARM.CalcType

This optional field specifies how the loan adjusts for rate changes. The default value of payments instructs the SCE to adjust the payment reflect the rate change. A value of balloon causes the teaser payment to persist during the rate cahnges, which results in a final balloon payment.

🟥 Data.ARM.FullyIndexedRate

The fields of this required object represent the data necessary to compute the fully indexed interest rate; that is, the Index + Margin.

Some lenders constrain the fully indexed rate to be rounded to the nearest something. e.g. If the Index + Margin is 7.123, an institution may require this rate to be rounded to the nearest 1/8^th of a percent which would produce 7.125%. Use the optional fields RoundBasis and RoundMethod to round the fully indexed rate.

Fields: 🔸Index, 🔸Margin, 🔹RoundBasis, 🔹RoundMethod

Objects: None

🔸 Data.ARM.FullyIndexedRate.Index

This required field holds the value of the published index interest rate appropriate for the loan at the time of closing. For the purpose of modeling the initial disclosure of the loan, this index rate remains constant through maturity.

🔸 Data.ARM.FullyIndexedRate.Margin

This required field holds the value of the margin that adds to the Index to produce the fully indexed rate. As with the Index field, this value remains constant throughout the loan.

🔹 Data.ARM.FullyIndexedRate.RoundBasis

If the value of this optional field is greater than zero, then the fully indexed rate will be rounded to this amount. Rounding the fully indexed rate to the nearest 1/8^th of one percent is a common practice. Making the RoundBasis equal to 0.125 will accomplish this objective.

🔹 Data.ARM.FullyIndexedRate.RoundMethod

If rounding of the fully indexed rate is required, the value of this field instructs the SCE how to direct the rounding. The settings below assume a RoundBasis of 0.01 or 1/100^th of a percent.

• nearest - Round to the nearest RoundBasis. 4.005 would round to 4.01.
• up - Round up to the nearest basis. 4.00001 would round to 4.01.
• down - Round down to the nearest basis. 4.00999 would round to 4.00.

🟥 Data.ARM.Limits

The constraints to a changing interest rate are represented as fields of this required object.

Fields: 🔸Annual, 🔸Ceiling, 🔸Floor, 🔸Lifetime

Objects: None

🔸 Data.ARM.Limits.Annual

The interest rate can change no more over any given year than the value of this required field.

🔸 Data.ARM.Limits.Ceiling

The absolute maximum an interest rate can be over the term of the loan is represented by the value of this required field.

🔸 Data.ARM.Limits.Floor

The absolute minimum an interest rate can be over the term of the loan is represented by the value of this required field.

🔸 Data.ARM.Limits.Lifetime

The Lifetime required field represents the maximum the interest rate can change over the lifetime of the loan.

🟦 Data.ARM.PostTeaser

The PostTeaser object defines the interest rate immediately following the teaser rate (see the Teaser object below).

By default, the post teaser rate will be the lesser of the FullyIndexedRate and the teaser rate plus the value of Limits.Annual. If this default behavior needs to be changed, use the fields of this optional object to mirror the lender's practices.

Note: The post teaser rate may be specified as either an increase to Teaser.Rate or an actual interest rate, according to the value of the PostTeaser.Type.

Fields: 🔹Ignore, 🔹ProRateInc, 🔸Rate, 🔹Type

Objects: None

🔹 Data.ARM.PostTeaser.Ignore

The post teaser rate is constrained by default by Limits.Floor and Limits.Ceiling. If the post teaser rate ignores either or both of these Limits, choose one of the values below of this optional field.

• Neither - Neither the Limits.Ceiling rate nor the Limits.Floor rate are ignored. Both are active constraints.
• Floor - The Limits.Floor rate is ignored.
• Ceiling - The Limits.Ceiling rate is ignored.
• Both - Both the Limits.Ceiling and Limits.Floor rates are ignored.

🔹 Data.ARM.PostTeaser.ProRateInc

The boolean value of this optional field determines whether or not the rate increase is pro-rated by the number of payments per year. This field requires the PostTeaser.Type field to be Increase.

For example, if the Teaser.Rate is 5.0% and the Limits.Annual is 2.0% on a quarterly loan, setting this field to true would increase the Teaser.Rate from 5.0 to 5.0 + 2.0/4 = 5.5% for the post teaser rate. The default behavior of false would have the post teaser rate be 5.0% + 2.0% = 7.0%.

🔸 Data.ARM.PostTeaser.Rate

The meaning of this required field depends on the value of the PostTeaser.Type field. Enter the value of the post teaser rate PostTeaser.Type = Rate) or rate increase PostTeaser.Type = Increase. In both cases, the rate is expressed as an annual rate.

🔹 Data.ARM.PostTeaser.Type

The value of this optional field determines if the PostTeaser.Rate is treated as an interest rate or an adjustment to the teaser rate.

• Increase - Increase the Teaser.Rate by the value of the PostTeaser.Rate field.
• Rate - The actual rate to be used after the Teaser.Rate is the value of the PostTeaser.Rate field.

🟥 Data.ARM.Teaser

The fields of this required object define the discount period of the loan.

Fields: 🔹ForceTerm, 🔹Ignore, 🔸Rate, 🔸Term

Objects: None

🔹 Data.ARM.Teaser.ForceTerm

If fully indexed rate equals the Teaser.Rate, the default behavior would be to output a single payment stream for the entire term of the loan. If, however, the teaser payment stream should always be displayed as an isolated payment stream, setting this optional field to true forces a teaser period to be displayed.

Example: A teaser rate of 4% for 36 months on a 120 month loan with a fully indexed rate of 4% might have an output similar to the following:

• If ForceTerm is true:

  36 payments of 920.14 at 4.0%
  84 payments of 920.14 at 4.0%
  

• If ForceTerm is false:

  120 payments of 920.14 at 4.0%
  

🔹 Data.ARM.Teaser.Ignore

The teaser rate is constrained by default by Limits.Floor and Limits.Ceiling. If the post teaser rate ignores either or both of these Limits, choose one of the values below of this optional field.

• Neither - Neither the Limits.Ceiling rate nor the Limits.Floor rate are ignored. Both are active constraints.
• Floor - The Limits.Floor rate is ignored.
• Ceiling - The Limits.Ceiling rate is ignored.
• Both - Both the Limits.Ceiling and Limits.Floor rates are ignored.

🔸 Data.ARM.Teaser.Rate

This rate is the fixed discount rate that applies for the Teaser.Term expressed as an annual percentage.

🔸 Data.ARM.Teaser.Term

The fixed term over which the discount rate or Teaser.Rate applies.

🟦 Data.ARM.TermStep

This optional object specifies the number of payments between interest rate changes after the teaser term has elapsed.

Fields: 🔹StairStepDown, 🔹Step

Objects: None

🔹 Data.ARM.TermStep.StairStepDown

If the fully indexed rate is less than the teaser rate, a value of false will keep the interest rate at the teaser rate for the duration of the loan. If your institution allows the rate to decrease below the teaser rate over the term of the loan, set the value of this field to true.

If the interest rate of the loan is decreasing, all of the Limits will be in effect and constrain the loan by their fields, but in reverse. So, for example, a loan with decreasing interest rate can decrease no more than the Limits.Annual amount over a given year.

🔹 Data.ARM.TermStep.Step

If the value of this field is greater than the number of payments per year, then any value is valid and the rate increase per step is equal to the annual rate increase.

If the value of this field is less than or equal to the number of payments per year, then the it must evenly divide the number of payments per year. In this case, the rate increase per step is equal to the annual rate increase multiplied by the term step divided by the number of payments per year.

🟦 Data.BalAdjs[]

The array of BalAdj objects allows the calling application to make one or more balance adjustments during the amortization of a loan to better support the quotation and servicing of open ended lending.

Fields: 🔹Adjust 🔸Date 🔹NewPmt 🔹Target

Objects: None

🔹 Data.BalAdjs[].Adjust

The Adjust field defines the amount by which to adjust the BegBal amount at the beginning of its amortization line. If, for example, the balance were $1,500 after the 12^th payment and an Adjust was 500.00 on 0012-00-00, the loan module would adjust the $1,500 balance by an additional $500, arriving at $2,000 as its EndBal.

🔸 Data.BalAdjs[].Date

The date of the balance adjustment. (Note the a balance will adjust after a payment that occurs on the same date.)

A special format allows for the adjustment to be made immediately after a specified payment index using the YYYY-00-00 mask. A date entry of 0018-00-00 instructs the Loan module to make an adjustment immediately after the 18^th payment.

🔹 Data.BalAdjs[].NewPmt

If the payment should change to reflect the balance adjustment, set the value of this field to true; otherwise, the payment will not change after this event.

🔹 Data.BalAdjs[].Target

The Target field defines what the balance should adjust to at the specified date. If, for example, the balance were $1,500 after the 12^th payment and a Target was defined as 2000.00 on 0012-00-00, the loan module would adjust the $1,500 balance to $2,000 as the EndBal of the BalAdj line in the amortization table.

🟦 Data.BusinessRules

Many loan calculation business rules may be toggled using the fields of this object.

Fields: 🔹AmError, 🔹AmortizeOnly, 🔹CanSkipFirst, 🔹CanSkipLast, 🔹ClosedFormEqn, 🔹LeapYearRound, 🔹MinFinChg, 🔹MinIntChg, 🔹MYED, 🔹OddFirstPmt, 🔹PmtAccrualCode, 🔹ProtMandatory, 🔹UsRuleAprException, 🔹YieldPPY, 🔹ZeroInterestRule

Objects: None

🔹 Data.BusinessRules.AmError

When amortizing a loan, often times there is a non-zero ending balance due to rounding. This field determines what to do (if anything) with a non-zero ending balance. This non-zero balance is referred to as the amortization error.

• Allow - Do not do anything with the non-zero ending balance.

• AdjPmt - Adjust the final payment to achieve perfect amortization, which will then result in an ending balance of zero.

• AdjPrin - Adjust the final principal reduction amount to achieve perfect amortization, which will then result in an ending balance of zero.

• AdjInt - Adjust the final interest reduction amount to achieve perfect amortization, which will then result in an ending balance of zero.

Note that using AdjPrin or AdjInt will cause the final payment to not equal the sum of the principal reduction amount and amount to interest in the amortization schedule.

🔹 Data.BusinessRules.AmortizeOnly

If the calling application sets the value of this field to true, then instead of computing a loan with payments that best amortize the principal balance to zero, the Loan module is instructed to simply amortize the specified loan (all advances and payments specified by the calling application) and return the ending balance.

To use this functionality, there are a few requirements that must be met:

• All specified payment streams must have a PmtType of other than CalcPmt. In AmortizeOnly mode, the Loan module will not compute "regular" principal and interest payments.

• No protection products may be requested.

• All advances must be specified, and not computed.

• AmError (see above) must be set to "Allow".

Furthermore, the output for an "AmortizeOnly" : true Loan request will omit the FedBox and Moneys response objects.

🔹 Data.BusinessRules.CanSkipFirst

Set this field to true to allow the first payment of a loan to be skipped. The default value of false does not allow a skipped first payment.

🔹 Data.BusinessRules.CanSkipLast

Set this field to true to allow the last payment of a loan to be skipped. The default value of false does not allow a skipped final payment.

🔹 Data.BusinessRules.ClosedFormEqn

When searching for the payment that best amortizes the loan to zero, this setting determines whether or not interest is rounded during the payment search algorithm. The default value of true indicates that the closed form equation should be matched, and interest will be left unrounded during the payment search algorithm. Setting this field value to false will cause interest to be rounded during the payment search algorithm.

🔹 Data.BusinessRules.LeapYearRound

If the value of this field is true and one of the actual/actual interest accrual calendars (including Midnight366) is used in the requested loan, then the interest accrued on a 365 days basis is rounded separately from the interest accrued on a 366 days basis. Note that this option is encountered very rarely in the marketplace.

If the value of this field is false, then interest computed on a 365 day basis will be added to the interest computed on a 366 day basis, and then rounded.

🔹 Data.BusinessRules.MinFinChg

This field allows the calling application to specify a minimum allowed finance charge for the loan. If a value greater than zero is specified, then the loan will be computed in the normal manner, along with the finance charge. If the computed finance charge falls below the specified minimum, then the final payment's interest charge will be adjusted to meet the specified minimum.

Note that the minimum interest charge is checked before the minimum finance charge. If the loan triggered a minimum finance charge adjustment, then the amount of this adjustment will be disclosed in the MinFinChgAdj field of the Moneys response object.

Note that since the minimum finance charge check is done after the loan payment and protection calculations have been completed, certain protection products whose calculations may vary due to a modified final payment will not reflect any minimum finance charge adjustments made to the final payment.

🔹 Data.BusinessRules.MinIntChg

This field allows the calling application to specify a minimum allowed interest charge for the loan. If a value greater than zero is specified, then the loan will be computed in the normal manner, along with the interest charge. If the computed interest charge falls below the specified minimum, then the final payment's interest charge will be adjusted to meet the specified minimum.

Note that the minimum interest charge is checked before the minimum finance charge. If the loan triggered a minimum interest charge adjustment, then the amount of this adjustment will be disclosed in the MinFinChgAdj field of the Moneys response object.

Note that since the minimum interest charge check is done after the loan payment and protection calculations have been completed, certain protection products whose calculations may vary due to a modified final payment will not reflect any minimum interest charge adjustments made to the final payment.

🔹 Data.BusinessRules.MYED

The MYED field represents the Mortgage Year End Date when computing an annual rest loan, a loan which is commonly encountered in the United Kingdom. If you do not need to compute an annual rest loan, then this field need not be included in the request.

If included in the request, then the value of the field must be in the format of "MM-DD" when MM is a valid month number from 1 to 12, and DD is a valid day number in the month specified. The month and day specified is the annual date on which escrowed payments and interest are applied to the outstanding principal balance.

When the MYED is specified, you must also specify a PmtStream object with a PmtType field value of PmtEsc, which indicates an escrowed payment.

🔹 Data.BusinessRules.OddFirstPmt

If the first payment should be adjusted (up or down) due to odd days interest in the same manner that interest is accruing in the loan, then set the value of this field true. A value of OnlyPositive instructs the SCE to only adjust the first payment due to odd days if there are positive odd days. Finally, a value of false instructs the SCE to not adjust the first payment using this method.

Note that you can not specify an odd first payment using this field and include ODI in the same request.

🔹 Data.BusinessRules.PmtAccrualCode

In rare instances, the calculated payment for a given loan is based upon a different accrual calendar than the one used to amortize interest in the amortization schedule. This is most commonly encountered when a system is not able to compute the "best" payment, and instead uses a simpler accrual calendar with a closed form equation (such as unit period simple). An estimated payment is computed, then used in the amortization schedule where interest is accrued on a different calendar. Note that this will almost always generate an ending balance of greater magnitude that the "correct" payment, unless the BusinessRules.AmError field is used to adjust the final payment.

A value of default means that the payment will be computed using the same accrual calendar as interest. Any other value will cause the computed payment to be calculated using the accrual code specified.

🔹 Data.BusinessRules.ProtMandatory

If the value of this field is set to true, then protection premiums/fees will be considered to be a part of the Finance Charge, and thus affect the Regulation Z APR.

🔹 Data.BusinessRules.UsRuleAprException

The US Rule APR Exception is an option used by some financial institutions that accrue interest in a US Rule manner, and also disclose the US Rule APR. If this field is omitted or set to false, the US Rule APR will always be computed.

If the value of this field is set to true and the following conditions are met: (i) interest is accrued via a US Rule method, (ii) A US Rule APR method matching the acrual method has been specified, (iii) the Regulation Z Finance Charge is equal to the interest charge, and (iv) there is only a single AccrualConfig object, then the US Rule APR will be disclosed as the interest rate.

🔹 Data.BusinessRules.YieldPPY

Canadian mortgages may compute periodic interest using a fractional power of a periodic yield. If set to a value other than "0", this value determines the period. Please contact us for further information if you support mortgage calculations in Canada. Note that when using this field with a value other than zero, the calling application must include an odd days prepaid fee in the request.

🔹 Data.BusinessRules.ZeroInterestRule

If the value of this field is true and (i) the interest rate for the entire term of the loan is 0%, or (ii) the computed interest charge for the loan is less than zero, then the interest charge will be set to a value of zero, and the Regulation Z Finance Charge will be adjusted in an identical manner.

Note that setting the value of this field to true will likely cause the sum of the principal and interest to no longer equal the total of payments (similarly for the Amount Financed and Finance Charge). J. L. Sherman and Associates does not recommend that you set the value of this field to true before consulting with your legal counsel in regards to these and other unforseen consequences.

Lastly, all payment rounding is forced to be rounded down to the nearest penny. This adjustment ensures that the sum of payments never exceeds the Principal Balance of the loan.

🟦 Data.Capitalize[]

Some loans require interest to be capitalized on specific dates, irrespective of any other considerations. For these events, use one or more Capitalize objects.

Fields: 🔹AllowFeb29, 🔸Date, 🔹Holidays, 🔹LastDay, 🔹PPY, 🔹SemimonthlyDay, 🔹Weekends

Objects: None

🔹 Data.Capitalize[].AllowFeb29

This field is used when generating event dates in a capitalization stream (if any) beyond the specified Date date of the Capitalize object. If the value of this field is true, then February 29th is an allowed date.

On the other hand, if the value of this field is set to false and a computed date in the given capitalization stream is scheduled to fall on February 29th, then the scheduled date will be altered in one of the following manners:

• If the number of payments per year is 1, 2, 4, 6, 12, or 24 then the scheduled date of February 29 will be moved back one day to February 28. This is the only date that will be adjusted.
• If the number of payments per year is 26 or 52 then the scheduled date of February 29 will be moved forward one day to March 1, and all subsequent dates will be a multiple of 7 or 14 days from this date (depending upon the specified payment frequency).

🔸 Data.Capitalize[].Date

The Date field for the Capitalize object is used to specify the date on which to capitalize interest. (For a stream of Capitilize events, see the Term field.) As an example, if interest is to be capitalized on Feb. 1, 2008, the field should be specified as "Date" : "2008-02-01".

🔹 Data.Capitalize[].Holidays

If event dates (including the specified start date) are not allowed to fall on specified holidays (see the Holidays[] array for more inforation on how to specify holidays), then set the value of this field to something other than ignore. The meaning of the other two values are defined below:

• prev - The date will be moved to the day before the holiday.
• next - The date will be moved to the Monday after the holiday.

Note that two other Capitalize fields can cause the computed dates to be adjusted: AllowFeb29 and Weekends. The rules for how these three fields interact are described below in detail.

For every date required in our capitalization stream, the SCE goes through the following steps:

1. Generate the next date in our date stream, called the target date.
2. If February 29th is not allowed and if the target date is 2/29, then adjust the target date forward or backward one day based upon the date generation frequency. If the frequency is a monthly multiple, then the target date is moved backward one day to 2/28. Weekly and biweekly frequencies move the target date forward one day to 3/1.
3. If weekend dates are not allowed (e.g. the Weekends field holds a value other than ignore) and the target date falls on a Saturday or Sunday:
   1. then adjust the target date according to the field value.
   2. if February 29th is not allowed and if the target date is 2/29, then adjust the target date in the same direction as in 3(a) above.
4. If holidays are not allowed (e.g. the Holidays field holds a value other than ignore) and the target date falls on a specified holiday:
   1. Then adjust the target date according to the Holidays field value.
   2. If weekend dates are not allowed (e.g. the Weekends field holds a value other than Ignore) and the target date falls on a Saturday or Sunday, then adjust the target date in the same direction as 4(a) above.
   3. if February 29th is not allowed and if the target date is 2/29, then adjust the target date in the same direction as in 4(a) above.
   4. Step 4 is repeated until the target date is not adjusted.

🔹 Data.Capitalize[].LastDay

This field is used to resolve ambiguitiess in subsequent event dates when the Date date falls on the last day of a month with fewer than 31 days.

Set this field's value to true if the intent was to make subsequent events occur on the last day of the month. A value of false indicates that subsequent event dates will fall on the day number specified by the Date.

As an example, if the calling application specifies a Date of "2010-02-28", then subsequent payment dates for a monthly payment frequency will be:

• on the 28th of each subsequent month if "LastDay" : false.
• on the last day of each subsequent month if "LastDay" : true.

🔹 Data.Capitalize[].PPY

PPY is an abbreviation for "payments per year", and as one might surmise, determines the frequency of capitalization events. If only one capitalization event occurs or the stream of capitilization events are monthly, this field may be ignored.

🔹 Data.Capitalize[].SemimonthlyDay

When specifying a semimonthly stream, the day number on which the first capitalization event occurs is the day number for all of the following odd numbered payments. If you omit this field or specify a value of 0, then the even numbered events will be generated using the default method within the SCE.

If you wish to specify the day number on which even numbered events fall (overriding the default method used in the SCE), then set the value of this field to the desired day number. Setting the value of this field to 31 will cause all even events to fall on the last day of the month.

As an example, if you want to specify a semi-monthly capitalization stream beginning on January 1, 2019 with events that fall on the 1st and 15th of each month for 24 payments, the object should look something like this:

{
  "Capitalization" : [
    {
      "Date" : "2019-01-01",
      "Term" : "24",
      "PPY" : "24",
      "SemimonthlyDay" : "15"
   }
  ]
}

🔹 Data.Capitalize[].Term

The Term field indicates the the number of capitalization events to be made at the specified payment frequency (see PPY above). The default value is 1, and if only one capitalization event is required, this field may be omitted.

🔹 Data.Capitalize[].Weekends

If capitalization stream dates (including the specified start Date) are not allowed to fall on a Saturday or Sunday, then set the value of this field to something other than ignore. The meaning of the other three values are defined below:

• prev - The date will be moved to the Friday before the computed weekend date.
• near - The date will be moved to the Friday before the computed weekend date if the computed weekend date falls on a Saturday, otherwise it will be moved to the Monday after.
• next - The date will be moved to the Monday after the computed weekend date.

Note that two other Capitalize fields can cause the computed dates to be adjusted - AllowFeb29 and Holidays. For a complete description of how these three fields work together, please see the documentation for the Holidays field.

🟦 Data.Construction

Fields: 🔸EndDate, 🔹HalfCommitment

Objects: None

If the requested loan calculation features a construction period, during which time interest only payments are made by the borrower, then the request need to include this object and set it's fields appropriately. Note that construction periods always begin on the date of the first advance.

Generally speaking, there are two methods used to disclose construction loans. The first method computes the total estimated interest due during the construction period, and treats it as an unfinanced prepaid fee. The second method discloses discrete interest only payments in the amortization schedule during the construction period.

To emulate the first method, simply include the Construction object and ensure that no payment events are set up to occur during the construction period. The construction interest will be computed and returned in the ConInterest response object with the IsPrepaid field set to true.

To emulate the second method, set up an interest only payment stream which begins during the construction period, with the final interest only payment occurring on the construction period's ending date. The interest only payments will then appear in the resulting amortization schedule, and the total construction interest will be returned in the ConInterest response object with the IsPrepaid field set to false.

🔸 Data.Construction.EndDate

The date on which the construction period terminates.

All dates must be in the form of "YYYY-MM-DD", and be 10 characters long. Hence, to end the construction period on July 4, 2021, the field would be specified as "EndDate" : "2021-07-04".

If the calling application sets up discrete interest only payments during the construction period, then the EndDate may also be specified as occurring on a given payment number (NNNN) as "EndDate" : "NNNN-00-00".

🔹 Data.Construction.HalfCommitment

During the construction period, if estimated interest should be disclosed based upon half of the commitment amount, then set the value of this field to true. If interest is due on the entire commitment amount during the construction period, then set this value to false. Multiple advance construction loans are computed with this field set as true.

🟦 Data.EditOutput

Changes to the presentation of the output data are contained in the fields of this object.

Fields: 🔹EarlyPayoffDate, 🔹Merge, 🔹PmtDollarRound, 🔹ShowAmTable, 🔹ShowFees, 🔹ShowGrandTot, 🔹ShowSubTot, 🔹ShowTap, 🔹ShowType, 🔹TagPmts

Objects: None

🔹 Data.EditOutput.EarlyPayoffDate

If an early payoff date is specified and is in the format of a valid date (i.e. YYYY-MM-DD), then the loan will first be computed normally, ignoring this value. Once this first step is done, the loan will then be amortized and the early payoff date applied by removing all loan events after the early payoff date, ensuring that a final payment date falls on the specified date.

If the early payoff date is specified and is in the format of NNNN-00-00, then the early payoff date will be set to the date of the N^th payment, and the loan will be computed as described above.

One common use of this field is to generate computed regular payments based upon a longer amortization term, with a final balloon payment made on the early payoff date (commonly called a balloon loan with a long term amortization and short term call).

All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, to end an early payoff date on July 1, 2021, the field would be specified as "EarlyPayoffDate" : "2021-07-01". To specify an early payoff date that coinsides with the 60th payment, the field would be specified as "EarlyPayoffDate" : "0060-00-00".

🔹 Data.EditOutput.KeepSlush

Rounding interest each period numerically eliminates values beyond two decimal places. This amount is referred to as slush. To keep this amount and add it to next period's unrounded interest, set the value of this field true.

🔹 Data.EditOutput.Merge

This field determines what should be done when a loan with multiple overlapping payment streams causes one or more payments to fall on the same calendar date. We strongly advise using either the none or ordered options as they are the most common and easiest to understand. The other two options (some and default) are provided for backwards compatibility, with some behaving as false and default behaving as true in versions of the SCE prior to the 2025-07 release.

Example: Two payment streams which generate payments that fall on the same date.

  "PmtStreams" : [
    { "Date" : "2025-03-01", "PmtType" : "CalcPmt", "Term" : "12"},
    { "Date" : "2025-04-01", "PmtType" : "PPY", "Term" : "4", "Term" : "4"}
  ]

The above JSON creates an array of two payment streams, with all of the quarterly interest only payments occurring on payment dates created by the first payment stream.

If the value of the Merge field is none, then payments will not be merged. That is, if multiple payments fall on the same date, then they will appear as separate payments in the amortization schedule, applied in the order listed in the request. In the sample above, this would cause the loan's amortization schedule to display two distinct payments in April, July, October, and January. Since the CalcPmt payments will be amortized first, the following PayInt payments will be payments of zero as no interest can accrue between the two payments on the same date. If the order of the PmtStream objects was reversed (with the PayInt type first and CalcPmt type second), then the PayInt payments would pay all interest due at the time, and the CalcPmt payments occurring on the same date as the PayInt payments would apply purely to principal.

If the value of this field is ordered, then payments will be merged. If multiple payments fall on the same date, then the payment associated with the last applicable payment steam listed in the request will take priority. In the sample above, this would cause the PayInt payments to take precedence over the CalcPmt payments in April, July, October, and January.

The some and default values are provided for backwards compatibility, and are no longer recommended for use.

🔹 Data.EditOutput.PmtDollarRound

Payments are normally rounded to the penny, according to the method specified by the EditInterest.PmtRound field. If the payment should be rounded to the dollar instead of the penny, then set the value of this field to true.

Note that for some loans (such as those with longer terms or relatively small proceeds), rounding the payment up or to the nearest dollar may require a shortened loan term to prevent one or more negative payments at the end of the loan.

🔹 Data.EditOutput.ShowAmTable

To supress the entire amortization schedule from the response, set value of this field to false; otherwise, the amortization schedule will be returned.

🔹 Data.EditOutput.ShowFees

If this field is set to false, then fees will not explicitly appear in the amortizaton schedule, unless they do not occur on the date of an advance or the date of a payment. They will also not be individually listed under the Moneys object of the response.

A value of true means that all fees will be explicitly accounted for, both in the Moneys response object as child objects and in the amortization table. The Type field will have the name of the fee as its value.

🔹 Data.EditOutput.ShowGrandTot

To show the amortization schedule grand totals in the response, set this field's value to true; otherwise, the grand totals will not be returned.

🔹 Data.EditOutput.ShowSubTot

To show the amortization schedule annual subtotals in the XML output, set this field's value to true; otherwise, annual subtotals will not be returned.

🔹 Data.EditOutput.ShowTap

If not specified, the default value of this field is determined by the Country specified. If the Country is GB (United Kingdom), then the default value is true. All other country values will default this field to false.

The value of this field determines if the total amount payable response field (i.e. TAP) will be computed and disclosed. This quantity is broadly defined as the total of payments plus fees that do not enter into the amortization table in any way.

🔹 Data.EditOutput.ShowType

Each line of the amortization schedule is characterized by a type, which describes the particular amortization event. An EditInterest event is different from a FixedPmt event, for example. Set this field to true to report the Type of each amortization event. A value of false will suppress output of the Type field in the amortization schedule.

🔹 Data.EditOutput.TagPmts

If the value of this field is set to true, then each PmtStream response object will include an Idx field which identifies the input payment stream object which gave rise to it. If this field is set to true, then the EditOutput.Merge field must be set to false. If both are set to true, then an error will be returned.

🟦 Data.EndBal

When computing a loan, the usual intention is to compute a payment which produces an ending balance of zero at the end of the repayment schedule. However, is some international markets (such as Australia / New Zealand), some loans are computed with a specified ending balance greater than zero. To support these types of loans, the EndBal field is provided.

If omitted, the desired ending balance at the end of the repayment schedule is defaulted to 0. To specify a desired ending balance greater than zero, simply specify the desired ending balance as an appropriately formatted currency value as the element's value.

For example, if the desired ending balance is $50,000.00, then you would include "EndBal" : "50000.00" in your request.

Note that if an ending balance greater than zero has been specified, then no protection products are allowed to be written with the loan, and the APR (and MAPR if requested) are not computed.

Fields: None

Objects: None

🟦 Data.Fees[]

This array of Fee objects allows the calling application to specify one ore more Fee objects to be added to the loan.

Fields: 🔹AddToFinChg, 🔹AddToPrin, 🔹Adjust, 🔹AllowFeb29, 🔸Amount, 🔹Blended, 🔹CalcType, 🔹Date, 🔹EqualServChg, 🔹Holidays, 🔹LastDay, 🔹MAPR, 🔹Max, 🔹Min, 🔹Name, 🔹Position, 🔹PPY, 🔹Round, 🔹RoundBasis, 🔹SemimonthlyDay, 🔹ServChgType, 🔹Term, 🔹Weekends

Objects: None

🔹 Data.Fees[].AddToFinChg

If this fee should be included in the computed Finance Charge (and hence, affect the APR), then set this field to true. The default value of false indicates that the fee does not affect the Finance Charge nor APR.

🔹 Data.Fees[].AddToPrin

If this fee should be added to the principal balance (e.g. the fee is financed along with the advance(s)), then set this field to true. If set to false, then the fee is paid up front out of the borrower's pocket.

🔹 Data.Fees[].Adjust

The optional Adjust field allows the calling application to increase or decrease the base amount on which a fee is calculated. If a negative value is specified and this adjustment would produce a negative base amount, then a value of zero is returned for the given fee. This field has no effect on fees with a CalcType of Dollar.

As an example, in Tennessee you may need to define a financed, non-APR affecting fee to be computed by decreasing the amount financed by $2,000, and then multiplying this reduced amount by 0.115. The way to accomplish this in the SCE is as follows:

{
  "Fees" : [
    {
      "Name" : "TN Fee",
      "CalcType" : "OnAmtFin",
      "Adjust" : "-2000.00",
      "Amount" : "0.115",
      "AddToPrin" : true,
      "AddToFinChg" : false
   }
  ]
}

🔹 Data.Fees[].AllowFeb29

This field is used when generating fee dates in a fee stream (if any) beyond the specified Date date of the Fee object. If the value of this field is true, then February 29th is an allowed fee date.

On the other hand, if the value of this field is set to false and a computed date in the given fee stream is scheduled to fall on February 29th, then the scheduled fee date will be altered in one of the following manners:

• If the number of payments per year is 1, 2, 4, 6, 12, or 24 then the scheduled fee date of February 29 will be moved back one day to February 28. This is the only date that will be adjusted.
• If the number of payments per year is 26 or 52 then the scheduled fee date of February 29 will be moved forward one day to March 1, and all subsequent fee dates will be a multiple of 7 or 14 days from this date (depending upon the specified payment frequency).

🔸 Data.Fees[].Amount

How this field is interpreted depends upon the Fee.CalcType field. Please see the documentation for this field for further information.

🔹 Data.Fees[].Blended

The Blended field determines how the SCE will include the fee with a payment or advance.

A value of true in an advance tells the SCE that the amount of the advance already includes the fee. A value of false means to add the fee on top of the existing advance.

Similarly, if the Fee occurs on a payment date, then true means that the payment has the fee already included in it, whereas a value of false means the fee is to be added on top of the payment.

🔹 Data.Fees[].CalcType

This field specifies how the fee is to be computed, as described in the following table.

🔹 Data.Fees[].Date

The date on which a fee occurs. If this object defines a stream of more than one fee, then this field defines the date on which the first fee occurs. If the date is the same as an advance or payment, the fee is loaded into the advance or payment event; otherwise, the fee is a stand-alone event. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, a fee date of January 2, 2021 would be specified as "Date" : "2021-01-02".

A special format is accepted for annual fees (Fee.PPY value of 1) paid on a specific calendar month of the year. Using 0000-MM-00 as a value for Date instructs the SCE to pay the fee on the MM payment of the payment stream. For example, 0000-06-00 instructs the system to pay this fee on June Payments.

If the Date field is not specified, then it will default to the earliest specified Advance Date.

🔹 Data.Fees[].EqualServChg

When a fee is set up as a service charge of type ByTerm (see Fee.ServChgType field), this field determines if all the service charge fee payments should be forced to be equal (a value of true), or if the final service charge fee payment can be different from the others due to rounding (a value of false).

🔹 Data.Fees[].Holidays

If fee dates (including the specified start date) are not allowed to fall on specified holidays (see the Holidays[] array for more inforation on how to specify holidays), then set the value of this field to something other than ignore. The meaning of the other two values are defined below:

• prev - The date will be moved to the day before the holiday.
• next - The date will be moved to the Monday after the holiday.

Note that two other Fee fields can cause the computed dates to be adjusted: AllowFeb29 and Weekends. The rules for how these three fields interact are described below in detail.

For every date required in our payment stream, the SCE goes through the following steps:

1. Generate the next date in our date stream, called the target date.
2. If February 29th is not allowed and if the target date is 2/29, then adjust the target date forward or backward one day based upon the date generation frequency. If the frequency is a monthly multiple, then the target date is moved backward one day to 2/28. Weekly and biweekly frequencies move the target date forward one day to 3/1.
3. If weekend dates are not allowed (e.g. the Weekends field holds a value other than ignore) and the target date falls on a Saturday or Sunday:
   1. then adjust the target date according to the field value.
   2. if February 29th is not allowed and if the target date is 2/29, then adjust the target date in the same direction as in 3(a) above.
4. If holidays are not allowed (e.g. the Holidays field holds a value other than ignore) and the target date falls on a specified holiday:
   1. Then adjust the target date according to the Holidays field value.
   2. If weekend dates are not allowed (e.g. the Weekends field holds a value other than Ignore) and the target date falls on a Saturday or Sunday, then adjust the target date in the same direction as 4(a) above.
   3. if February 29th is not allowed and if the target date is 2/29, then adjust the target date in the same direction as in 4(a) above.
   4. Step 4 is repeated until the target date is not adjusted.

🔹 Data.Fees[].LastDay

This field is used to resolve ambiguitiess in subsequent fee dates when the Date falls on the last day of a month with fewer than 31 days. If the value of the Date field is not a valid date, then the value of this field is ignored. If the value of the Term field is 1, then the value of this field is ignored.

Set this field's value to true if the intent was to make subsequent fees occur on the last day of the month. A value of false indicates that subsequent fee dates will fall on the day number specified by the Date field.

As an example, if the calling application specifies a Date of 2010-02-28, then subsequent fee dates for a monthly fee frequency will be:

• on the 28th of each subsequent month if "LastDay" : false.
• on the last day of each subsequent month if "LastDay" : true.

🔹 Data.Fees[].MAPR

If you wish to compute the Military APR, then certain fees may not be considered Regulation Z APR affecting fees, but are considered Military APR affecting fees. In this case, you will need to set the value of this field to true.

Fees which are added to the finance charge (e.g. "AddToFinChg" : true are always considered MAPR fees, regardless of the stated value of this field.

Note that debt protection products are automatically included in the calculation of the Military APR, no matter what method is used for payment (e.g. single premium vs. monthly outstanding balance).

🔹 Data.Fees[].Max

If a maximum value for the fee is specified and is greater than zero, then if the computed fee exceeds this maximum value, then the maximum value will be used instead. If no maximum value is specified or is set to a value of zero, then no maximum will be enforced. Please note that this field is applied to all fee types supported. Also, note that a specified maximum value is checked after enforcing a specified minimum value, and hence a specified maximum value trumps a specified minimum.

🔹 Data.Fees[].Min

If a minimum value for the fee is specified and is greater than zero, then if the computed fee is less than this minimum value, then the minimum value will be used instead. If no minimum value is specified or is set to a value of zero, then no minimum will be enforced. Please note that this field is applied to all fee types supported. Also, note that a specified minimum value is checked before enforcing a specified maximum value, and hence a specified maximum value trumps a specified minimum.

🔹 Data.Fees[].Name

This field is for convenience purposes only, and does not affect the calculation of the fee in any manner. However, the value of this field will be used to identify the fee in the response, and hence it is highly recommended that you name your fees accordingly.

🔹 Data.Fees[].Position

Fees inflence a loan depending on when they are applied.

• OnAdvance means that the fee is included in the application of an advance.
• BeforePmt means that when the fee occurs on the same date as a payment, the fee is calculated before the payment amortizes the loan.
• InPmt means that the fee is included as part of the payment.
• AfterPmt means that when the fee occurs on the same date as a payment, the payment first amortizes the loan, then the fee is calculated and applied.
• NotInPmt means that the fee is paid on the same date as a payment but is not reflected in that payment. If the fee has "AddToFinChg" : true, it is called a "Pocket APR" fee; otherwise, it is a straight "Pocket Fee".
• Default means different things, depending on when the fee occurs:
  • A fee on an advance is treated as if OnAdvance were selected.
  • A fee on a payment is treated as if InPmt were selected.

🔹 Data.Fees[].PPY

PPY is an abbreviation for "payments per year", and in the case of the Fee object, determines the frequency for the fee stream. If the value of the Term field is 1, then the value of this field is ignored.

🔹 Data.Fees[].Round

The value of this field, along with the with the Fee.RoundBasis field described below, determine how the amount on which the fee is based upon is to be rounded.

For fee calculation types of OnPrincipal, OnProceeds, OnAmtFin, OnBalance, and OnBalanceFlat, the amount on which the fee is based is fairly self evident: the starting principal balance, proceeds, amount financed, or the outstanding balance at the time that the fee is assessed. Thus, if the calling application requires a fee to be computed based upon 0.35% of the principal balance rounded to the nearest $100, then the fee object would look something like this:

{
  "Fees" : [
    {
      "Name" : "Doc Stamp",
      "CalcType" : "OnPrincipal",
      "Amount" : "0.35",
      "Round" : "nearest",
      "RoundBasis" : "100.00",
      "AddToPrin" : true,
      "AddToFinChg" : false
   }
  ]
}

For the Dollar fee calculation type, the amount on which the fee is based is defined as the fee amount passed into the engine. This allows the calling application to pass in a precomputed fee amount and have the SCE round it as directed. As an example, here is the definition of a dollar fee which is rounded up to the next dollar (the value of the fee below would then be $25 after rounding):

{
  "Fees" : [
    {
      "Name" : "Doc Stamp",
      "CalcType" : "Dollar",
      "Amount" : "24.25",
      "Round" : "up",
      "RoundBasis" : "1.00",
      "AddToPrin" : true,
      "AddToFinChg" : false
   }
  ]
}

For the ServChg fee calculation type, the amount on which the fee is based is defined as the computed service charge amount, as defined by the Amount and ServChgType fields.

🔹 Data.Fees[].RoundBasis

When rounding the amount on which the fee is based, the value of this field determines the precision to which rounding is performed. The default value of 0.01 indicates that the rounding should be done to the penny, whereas a value of 100.0 indicates that rounding should take place to the nearest hundred dollars.

🔹 Data.Fees[].SemimonthlyDay

When specifying a semimonthly fee stream, the day number on which the first fee is added determines the day number for all of the following odd numbered payments. If you omit this field or specify a value of 0, then the even numbered fees will be generated using the default method within the SCE. If the value of the Term field is 1, then the value of this field is ignored.

If you wish to specify the day number on which even numbered fees fall (overriding the default method used in the SCE), then set the value of this field to the desired day number. Setting the value of this field to 31 will cause all even fees to fall on the last day of the month.

As an example, if you want to specify a semi-monthly $10 fee stream beginning on January 1, 2015 with fees that fall on the 1st and 15th of each month for 48 fees, the object should look something like this:

{
  "Fees" : [
    {
      "Name" : "Test Fee",
      "Date" : "2015-01-01",
      "Amount" : "10.00",
      "Term" : "48",
      "PPY" : "24",
      "SemimonthlyDay" : "15"
   }
  ]
}

🔹 Data.Fees[].ServChgType

This field dictates whether or not a fee is treated as a service charge, and if so, determines how the service charge dollar amount is paid off over the term of the loan. If a fee should not be treated as a service charge, then the default value of None should be specified.

• ByTerm means that the service charge is paid off by dividing the amount by the Term field of the same Fee object.
• ByDays means that the service charge is paid off on payment dates. The amount of the fee is calculated as the number of days from the previous payment (or advance) divided by the total number of days in the term of the fee.

🔹 Data.Fees[].Term

The Term field determines the the number of fees to be included at the specified frequency (see Fee.PPY above), after which the fee stream is completed. The default value is 1. If the value of the Date field is not a valid date, then the value of this field is ignored.

🔹 Data.Fees[].Weekends

If fee dates (including the specified start Date) are not allowed to fall on a Saturday or Sunday, then set the value of this field to something other than ignore. The meaning of the other three values are defined below:

• prev - The date will be moved to the Friday before the computed weekend date.
• near - The date will be moved to the Friday before the computed weekend date if the computed weekend date falls on a Saturday, otherwise it will be moved to the Monday after.
• next - The date will be moved to the Monday after the computed weekend date.

Note that two other Fee fields can cause the computed dates to be adjusted - AllowFeb29 and Holidays. For a complete description of how these three fields work together, please see the documentation for the Holidays field.

🟦 Data.Format

The Format object is one of the first objects parsed from a request, as various fields affect how date and numeric fields are parsed and validated.

Fields: 🔹CurrencyDecimals, 🔹DateFormat, 🔹DateSeparator, 🔹DecimalSeparator, 🔹StrictDP, 🔹ThousandSeparator

Objects: None

🔹 Data.Format.CurrencyDecimals

When displaying and parsing Currency fields, this field determines the maximum number of decimal places allowed after the DecimalSeparator. If this field is not included, the default value will be determined by the value of the Country field. For most countries, the default value is 2. If no country code is specified, then the default value for this field is 2.

🔹 Data.Format.DateFormat

When displaying and parsing Date fields, this field determines the expected format for all Date fields. The following DateFormat options are allowed:

• YMD - All dates should be formated as YYYY-MM-DD.
• MDY - All dates should be formated as MM-DD-YYYY.
• DMY - All dates should be formated as DD-MM-YYYY.

Note that the character which separates the individual month, day, and year portions of the date is configurable via the DateSeparator field.

🔹 Data.Format.DateSeparator

When displaying and parsing Date fields, this field determines the character used to separate the individual month, day, and year portions of a date field.

🔹 Data.Format.DecimalSeparator

When displaying and parsing Currency, Percentage, or Floating numeric fields, this field determines the character used to separate the fractional part from the whole.

🔹 Data.Format.StrictDP

If the value of this field is true, then the SCE will strictly verify the number of decimal places allowed for currency input values. Thus, if the calling application sends in a request with a currency amount of 1000.005, the SCE will return an error code.

If the value of this field is set to false, then currency values sent in with an invalid number of decimal places will be rounded to the correct number of decimal places by the SCE (using five/four rounding), and a warning message with this information will be returned with the response.

🔹 Data.Format.ThousandSeparator

When displaying numeric fields, this field determines the character used to separate the thousands places from the hundreds. When parsing a numeric request field, if a thousand separator is specified in the request, then the SCE will now remove all occurrences of the specified thousand separator from the numeric field string before attempting to convert it to a number.

🟦 Data.Holidays[]

If dates for PmtStream and Fee objects have requested that holidays be skipped (e.g. the Holidays field for the object in question is set to a value other than ignore, then the request must specify each holiday to be considered, with each holiday requiring at least one entry in this Holidays[] array.

The format of the Holidays[] array member must follow one of the three following descriptions:

• YYYY-MM-DD - A holiday can be defined by sending in a valid date, where YYYY is greater than or equal to 1900, MM is a valid month, and DD is a valid day for the given year and month.
• 0000-MM-DD - A holiday that occurs annually on the same month and day can be defined by sending in a valid month and day, with the year passed in as 0000. As an example, in the United States of America, Christmas is a Federal holiday celebrated on December 25th of each year. To pass this holiday in to the SCE, the Holidays[] array member would look like "0000-12-25".
• 0001-MM-PD - A holiday that occurs annually in the same month on a given day of the week (D) in a given position in the month (P) can be defined by sending in a valid month, position, and day of the week, with the year passed in as 0001. The value of D can be from 0 to 6, where 0 = Sunday, 1 = Monday, ..., 6 = Saturday. The value of P can be from 1 to 6, where 1 = 1st, 2 = Second, ..., 5 = 5th, 6 = last. As an example, in the United States of America, Thanksgiving is a Federal holiday celebrated on the 4th (P=4) Thursday (D=4) of November (MM=11) every year. To pass this holiday in to the SCE, the Holiday[] array member would look like "0001-11-44".
• 0002-NN-NN - A holiday that occurs annually, but can not be expressed using any of the above methods. Currently, the following special holidays are recognized by the SCE:
  • 00-01 - Good Friday
  • 00-02 - Easter Sunday
  • 00-03 - Easter Monday

Fields: None

Objects: None

🟦 Data.MI

The MI object determines if this loan includes one of the supported types of mortgage insurance (MI) -- PMI or FHA. This object contains fields which further specify mortgage insurance options.

NOTE: Mortgage insurance is only supported on equal, balloon, and interest only loan builder requests at this time.

Fields: 🔹CashDown, 🔹LoanAmt, 🔸PropertyValue, 🔹Type

Objects: 🟦 Periodic, 🟥 Rates[], 🟦 UpFront

🔹 Data.MI.CashDown

The CashDown field represents a cash down payment made at closing. If specified and greater than zero, this amount will be deducted from the principal balance. If not specified, the cash down payment will default to zero.

🔹 Data.MI.LoanAmt

This field represents the amount by which the PMI rates are multiplied to produce a level PMI premium. If not specified, then the principal balance will be used to compute the annual premium.

🔸 Data.MI.PropertyValue

This field's value represents the appraised property value, and will be used in the calculation of the loan to value ratio.

🔹 Data.MI.Type

This field determines the type of mortgage insurance to include with the loan. If the value of this field is set to fha, then a different MI premium is computed every twelve months based upon the average outstanding principal balance during that same term. The MI calculation adheres strictly to the HUD regulation.

If the value of this field is set to pmi, then each defined MI rate produces a level MI premium based upon the inital loan amount.

🟦 Data.MI.Periodic

The fields of this object determine the conditions when MI is no longer included.

Fields: 🔹DropLTV, 🔹Term, 🔹WarnLTV

Objects: None

🔹 Data.MI.Periodic.DropLTV

The value of this field determines the loan to value ratio at which MI should be removed, and is expressed as a percentage. For example, if you wish to automatically drop MI when the loan to value ratio first equals or falls below 78%, then you would specify "DropLTV" : "78.0".

🔹 Data.MI.Periodic.Term

The value of this field represents the the term (in payments) beyond which MI will be removed.

As an example, if mortgage insurance must be removed after the 180th payment, then the calling application should specify

{
  "MI" : {
    "Periodic" : { "Term" : "180"}
 }
}

🔹 Data.MI.Periodic.WarnLTV

The value of this field determines the loan to value ratio at which a warning should be issued, and is expressed as a percentage of LTV (loan to value). For example,if you wish to know when the loan to value ratio first equals or falls below 80%, then you would specify "WarnLTV" : "80.0".

🟥 Data.MI.Rates[]

This array if Rate objects defines the rates used to compute MI on the loan. There must be at least one Rate object in the Rates[] array, and there can be more than one if rates are set to switch at a specified payment number.

Fields: 🔸Rate, 🔹Switch

Objects: None

🔸 Data.MI.Rates[].Rate

The value of this field specifies the cost of mortgage insurance per $100 of the loan amount. As an example, a loan computed with a MI rate of $1.50 per $100 would be specified as

{
  "MI" : {
    "Rates" : [
      { "Rate" : "1.50"}
    ]
 }
}

🔹 Data.MI.Rates[].Switch

This optional field defines the payment number beyond which the associated MI rate will apply. If not specified, the value will default to zero.

Thus, if there is only a single MI rate, one may omit this field (see example above).

Example of a MI multiple rate structure (use a rate of $1.50 for the first 10 years, with a rate of $0.20 for coverage beyond 10 years):

{
  "MI" : {
    "Rates" : [
      { "Rate" : "1.50"},
      { "Rate" : "0.20" , "Switch" : "120"}
    ]
 }
}

🟦 Data.MI.UpFront

This object determines if there is an up front fee for mortgage insurance, and if so, how it is computer. If this object is not present in the request, then no up front fee will be computed. Note that ZOMP (zero option monthly premium) products do not have an up front fee, which means that this object should be omitted.

Fields: 🔹Paid, 🔹Reduce, 🔹Units, 🔹Value

Objects: None

🔹 Data.MI.UpFront.Paid

If the value of this field is set to financed, then the computed up front fee will be added to the principal balance and the finance charge. A value of atclosing will cause the value of the fee to be added to the finance charge alone. Finally, a value of bylender means that the up front fee is to be paid by the lender, hence the value of the fee is not added to either the principal balance nor the finance charge.

🔹 Data.MI.UpFront.Reduce

If the specified number of periodic premiums to include as an up front fee is greater than zero, then this field determines if the term of coverage for PMI will be reduced by the same amount.

🔹 Data.MI.UpFront.Units

If the Units field is set to months, then UpFront.Value represents the number of periodic MI premiums to be paid at closing.

If the Units field is set to Years, then UpFront.Value represents the number of annual MI premiums to be paid at closing. Many single premium products define the up front fee as a number of years of MI to be paid up front.

Finally, if the Units field is set to Points, then UpFront.Value represents the percentage of principal to be paid up front. As of October 3, 2011, FHA loans use points.

🔹 Data.MI.UpFront.Value

If part of the MI fees are to be paid up front, then value of this field must be grater than zero. How the value of this field is interpreted depends upon the Units field (see below).

The default value of zero means that no up front fee will be computed.

🟦 Data.ODI

If odd days should be treated as a prepaid finance charge or added to the first payment in a manner different from how interest is accruing (see BusinessRules.OddFirstPmt), then the request needs to define how odd days interest is computed and handled using the fields of this object.

Fields: AccrualCode 🔹AddToPmt, 🔹AddToPrin, 🔹AnchorDate, 🔹ForceUnitPeriod, 🔹NoCap, 🔹UseDailyCost, 🔹UseNegODI

Objects: None

🔹 Data.ODI.AccrualCode

The accrual code defines how the odd days interest is computed. The meaning of the allowed accrual codes is defined below.

Note that accrual code 250 ("Variable Days Per Year") defines the basis divisor days to be equal to 12 multiplied by the number of days in the month of the date on which interest begins to accrue. Thus, if the interest start date falls in November, then the number of basis days is 360. If the interest start date falls in a month with 31 days, then the number of basis days is 372. For an interest start date in February, the number of basis days will either be 336 or 348, depending upon whether or not it is a leap year.

🔹 Data.ODI.AddToPmt

If the calling application wants the odd days interest to be added to the first payment, then set the value of this field to true. A value of false indicates that the odd days interest will be treated as a prepaid finance charge.

🔹 Data.ODI.AddToPrin

If any odd days interest should be treated as a financed prepaid fee, then set the value of this field to true. Note that if both AddToPmt and AddToPrin are set to true, then a warning message will be returned by the SCE and the value of AddToPrin will be set to false.

🔹 Data.ODI.AnchorDate

The computed number of odd days is the number of days between the loan date and the anchor date. This field determines how to arrive at the anchor date. A value of BackUnitPeriod means that the anchor date is one unit period prior to the specified first payment date. A value of BackDaysPerPeriod means that the anchor date is the number of days per period prior to the first payment date. Please note that for both of these methods, the period used will be that associated with the payment stream in which the first payment occurs.

🔹 Data.ODI.ForceUnitPeriod

Some unit period methods will not use a strict unit period interest accrual factor in the period to the first payment. For example, code 302 will count the days to the first payment and divide by 365. For a monthly loan, setting this field to true will use a 1/12 factor instead of Days/365.

🔹 Data.ODI.NoCap

When the odd days interest is financed, setting this field to true prevents interest from being computed on interest. The default is false, which means interest will be computed on interest.

🔹 Data.ODI.UseDailyCost

If the total odd days prepaid fee is computed by first generating a rounded (to the nearest penny) daily cost and then multiplying this value by the computed number of odd days, then set the value of this property to true.

A value of false means that the daily cost is left unrounded, and the total prepaid fee is rounded after the computation is complete.

🔹 Data.ODI.UseNegODI

If there are negative odd days in the loan, then the value of this field determines if a negative odd days interest fee is computed. If the value of this field is false, then negative odd days fees are not allowed, the SCE will return a value of zero in this situation, and the computed payment will be adjusted to take into account the negative odd days. A value of true will return a negative odd days interest fee (in effect, it then becomes and odd days interest credit) when there are negative odd days in a loan.

🟦 Data.PmtStreams[]

Payment streams are defined using the fields of this empty object, including individually defined payments.

Fields: 🔹AllowFeb29, 🔹Amount, 🔹ComputeTerm, 🔸Date, 🔹Holidays, 🔹LastDay, 🔹MinPmt, 🔹PmtType, 🔹PPY, 🔹ReplaceIdx, 🔹SemimonthlyDay, 🔹Term, 🔹Weekends

Objects: None

🔹 Data.PmtStreams[].AllowFeb29

This field is used when generating payment dates (if any) beyond the specified PmtStreams[].Date. If the value of this field is true, then February 29th is an allowed payment date.

On the other hand, if the value of this field is set to false and a computed date in the given payment stream is scheduled to fall on February 29th, then the scheduled payment date will be altered in one of the following manners:

• If the number of payments per year is 1, 2, 4, 6, 12, or 24 then the scheduled payment date of February 29 will be moved back one day to February 28. This is the only date that will be adjusted.

• If the number of payments per year is 26 or 52 then the scheduled payment date of February 29 will be moved forward one day to March 1, and all subsequent payment dates will be a multiple of 7 or 14 days from this date (depending upon the specified payment frequency).

🔹 Data.PmtStreams[].Amount

The value of the Amount field has different meanings depending upon the PmtType selected. Please see the documentation on the PmtType field below for more information on how these two fields work together to define a payment stream.

If the PmtType field is equal to CalcPmt, then the value of this field may be specified as a flat dollar amount (e.g. "Amount" : "250.00") which represents an additional amount to be added to the computed payment (this is also know as a pickup payment), or a percentage of the computed payment (e.g. "Amount" : "200%"), which allows the calling application to specify a double payment, half payment, etc.

If the PmtType field is equal to FixedPmt, then the value of this field may be specified as a flat dollar amount (e.g. "Amount" : "250.00"), a percentage of the principal balance (e.g. "Amount" : "5.25%"), or a percentage of the outstanding balance at the time the payment is made (e.g. "Amount" : "8.125%B").

If the PmtType field is equal to PayInt or PayPrin, then the value of this field may be specified as a flat dollar amount (e.g. "Amount" : "250.00"), a percentage of the principal balance (e.g. "Amount" : "5.25%"), a percentage of the outstanding balance at the time the payment is made (e.g. "Amount" : "8.125%B"), or a percentage of the computed target payment (e.g. "Amount" : "100%C").

If the PmtType field is equal to CalcPmt, then the value of this field may be specified as a flat dollar amount (e.g. "Amount" : "500.00") which will be added to the computed payment, or a percentage of the computed payment (e.g. "Amount" : "200%"), which allows the calling application to specify a double payment, half payment, etc.

🔹 Data.PmtStreams[].ComputeTerm

If set to true, then the ComputeTerm field is used to inform the Loan module that the calling application is requesting an equal payment "roll to term" loan calculation. In this loan scenario, the calling application specifies the interest rate, amount requested, maximum desired payment amount, and maximum loan term. The Loan module will then compute the shortest loan term to produce an equal payment amount less than or equal to the specified maximum payment.

As an example, the following partial JSON request would direct the Loan module to compute the term for an equal payment loan with an interest rate of 5.00%, an advance of $5,000, a maximum desired payment amount of $300, and a maximum allowed loan term of 60 monthly payments:

{
  "Advances" : [
    {
      "Date" : "2019-01-01",
      "Amount" : "5000.00"
   }
  ],
  "AccrualConfigs" : [
    {
      "Date" : "2019-01-01",
      "IntRate" : "5.000",
      "AccrualCode" : "301"
   }
  ],
  "PmtStreams" : [
    {
      "Date" : "2019-02-01",
      "PmtType" : "FixedPmt",
      "Amount" : "300.00",
      "Term" : "60",
      "ComputeTerm" : true
   }
  ]
}

Note that in the above partial JSON request, the PmtType must be set to FixedPmt, the value of the Amount field is set to the maximum desired payment amount, and the value of the Term field is set to the maximum term allowed.

🔸 Data.PmtStreams[].Date

The Date field for the PmtStream object is generally used to specify the starting date for the payment stream in question. As an example, if the payment stream should begin on Feb. 1, 2021, then the field should be specified as "Date" : "2021-02-01".

For payment frequencies that are monthly multiples, the day number specified in this field specifies the desired day number of all future payments, if this day number does not exceed the number of days in the computed month. As an example, if the first payment is scheduled to be made in February of 2022 and the desired day for all payments is the 30th, then the field would be specified as "Date" : "2022-02-30".

However, to provide power and flexibility to the calling application, the SCE will also understand Date values in the following formats:

• NNNN-00-00 If you wish to replace a previously defined payment by specifying the payment number (N), use a value of NNNN-00-00. An field value of 0012-00-00 instructs the engine to replace the 12th payment. If the value of the Term field (T) is specified and greater than one, then the Nth through (N+T-1)th payments will be replaced.

Example: To define a stream of 12 interest only payments followed by 48 computed payments, the following JSON could be used:

{
  "PmtStreams" : [
    {
    "Date" : "2014-12-20",
    "PmtType" : "CalcPmt",
    "Term" : "60",
    "PPY" : "12"
   },
    {
    "Date" : "0001-00-00",
    "PmtType" : "PayInt",
    "Term" : "12"
   }
  ]
}

• 0000-MM-00 If you wish to define monthly replacement payments, use a value formatted as 0000-MM-00, where MM is a two digit month number in [1...12]. A value of 0000-06-00 instructs the SCE to use the defined payment for every payment occurring in the month of June.

Example: To define a stream of 60 payments with every payment in July and August skipped, the following JSON could be used:

{
  "PmtStreams" : [
    {
    "Date" : "2014-12-20",
    "PmtType" : "CalcPmt",
    "Term" : "60",
    "PPY" : "12"
   },
    {
    "Date" : "0000-07-00",
    "PmtType" : "FixedPmt",
    "Amount" : "0"
   },
    {
    "Date" : "0000-08-00",
    "PmtType" : "FixedPmt",
    "Amount" : "0"
   }
  ]
}

• YYYY-MM-00 If you wish to define replacement payments occurring in a specified year and month, use a value formatted as YYYY-MM-00, where MM is a two digit month number from 01 through 12, and YYYY is a four digit year. A value of 2021-08-00 instructs the SCE to use the defined payment for every payment occurring in August of 2021 (there can be more that one payment if the payment frequency is greater than monthly).

Note: if the value of the Date field is not a valid date (i.e. it is instead of one of the three formats mentioned above), then the LastDay, Term, and PPY fields will be ignored, unless otherwise noted above.*

🔹 Data.PmtStreams[].Holidays

If payment dates (including the specified start date) are not allowed to fall on specified holidays (see the Holidays[] array for more inforation on how to specify holidays), then set the value of this field to something other than ignore. The meaning of the other two values are defined below:

• prev- The date will be moved to the day before the holiday.
• next- The date will be moved to the Monday after the holiday.

Note that two other PmtStreams[] fields can cause the computed dates to be adjusted: AllowFeb29 and Weekends. The rules for how these three fields interact are described below in detail.

For every date required in our payment stream, the SCE goes through the following steps:

1. Generate the next date in our date stream, called the target date.
2. If February 29th is not allowed and if the target date is 2/29, then adjust the target date forward or backward one day based upon the date generation frequency. If the frequency is a monthly multiple, then the target date is moved backward one day to 2/28. Weekly and biweekly frequencies move the target date forward one day to 3/1.
3. If weekend dates are not allowed (e.g. the Weekends field holds a value other than ignore) and the target date falls on a Saturday or Sunday:
   1. then adjust the target date according to the field value.
   2. if February 29th is not allowed and if the target date is 2/29, then adjust the target date in the same direction as in 3(a) above.
4. If holidays are not allowed (e.g. the Holidays field holds a value other than ignore) and the target date falls on a specified holiday:
   1. Then adjust the target date according to the Holidays field value.
   2. If weekend dates are not allowed (e.g. the Weekends field holds a value other than Ignore) and the target date falls on a Saturday or Sunday, then adjust the target date in the same direction as 4(a) above.
   3. if February 29th is not allowed and if the target date is 2/29, then adjust the target date in the same direction as in 4(a) above.
   4. Step 4 is repeated until the target date is not adjusted.

🔹 Data.PmtStreams[].LastDay

This field is used to resolve ambiguitiess in subsequent payment dates when the Date date falls on the last day of a month with fewer than 31 days. If the value of the Date field is not a valid date, then the value of this field is ignored.

Set this field's value to true if the intent was to make subsequent payments occur on the last day of the month. A value of false indicates that subsequent payment dates will fall on the day number specified by the Date.

As an example, if the calling application specifies a Date of 2010-02-28, then subsequent payment dates for a monthly payment frequency will be:

• on the 28th of each subsequent month if "LastDay" : false.
• on the last day of each subsequent month if "LastDay" : true.

🔹 Data.PmtStreams[].MinPmt

If specified, this field will dictate a minimum payment. If a calculated payment falls below the specified minimum payment value, then the minimum payment value will be used instead.

When a minimum payment is used, the principal reduction of the loan will be accelerated. In some loan scenarios, this will result in an early payoff of the loan before the specified Term of the payment stream. In this situation, the final payment will always pay off the loan, and will be smaller than the specified minimum payment.

🔹 Data.PmtStreams[].PmtType

Various types of payment streams may be requested by use of this field. Please note that the meaning of the Amount field changes according to the PmtType selected. Each payment type is detailed below.

• FixedPmt - the Amount field represents the exact dollar amount of the payment.
• PayInt - all interest due is to be paid, and the value of the Amount field determines the principal reduction to be applied in addition to the payment of interest. If the value of Amount is zero, then this equates to an interest only payment.
• PayPrin - the value of Amount is treated as a pure principal reduction amount.
• CalcPmt - calculate the payment. If the value of the Amount field is greater than zero (but not specified as a percentage), then it is treated as a pickup amount to be paid in addition to the computed payment. If the Amount is expressed as a percentage, then the payment amount will be multiplied by the desired percentage (which allows for double or triple payments, etc.)
• PmtEsc - When computing an annual rest loan (see the BusinessRules.MYED field), the payment stream needs to specify a PmtType field value of PmtEsc to indicate an escrowed payment.

When two payments occur on the same date, they merge into one payment according to the following rules:

• PayInt and PayInt - Add the two Amounts together, so long as one is an interest only payment, or if both types use the same method to specify the principal payment amount (e.g. both use fixed dollar amounts, or both us percentages of principal).
• PayInt and PayPrin - If the same conditions mentioned in the previous case exist, then the Amount of the PayInt event will be increased by the PayPrin Amount. Delete the PayPrin event.
• PayInt and CalcPmt - Replace the CalcPmt event with the PayInt event.
• PayInt and FixedPmt - Keep both events separate.
• CalcPmt and PayPrin - If the PayPrin Amount is specified as a fixed dollar amount, then increase the Amount of the CalcPmt by the PayPrin Amount and delete the PayPrin event.
• CalcPmt and CalcPmt - Add the Amounts together.
• CalcPmt and FixedPmt - Replace the CalcPmt event with the FixedPmt event.
• FixedPmt and PayPrin - If the PayPrin Amount is specified as a fixed dollar amount, then increase the Amount of the FixedPmt by the PayPrin Amount and delete the PayPrin event.
• FixedPmt and FixedPmt - Keep both events separate.
• PayPrin and PayPrin - Keep both events separate.

🔹 Data.PmtStreams[].PPY

PPY is an abbreviation for "payments per year", and as one might surmise, determines the payment frequency for the payment stream. If the value of the Date field is not a valid date, then the value of this field is ignored.

🔹 Data.PmtStreams[].ReplaceIdx

The ReplaceIdx field allows applications to restrict the enforcement of a replacement payment to a specific PmtStream. If specified, the value of ReplaceIdx must be an integer >= 0. If not included in the request, then ReplaceIdx will be set internally to a value of -1, which means that this replacement payment rule will be applied to all matching payments.

If specified, the value of ReplaceIdx represents the numeric index of the PmtStreams[] object to which the replacement payment will only be applied.

Example 1:

{
  "PmtStreams" : [
    {
    "Date" : "2024-01-01",
    "PmtType" : "PayInt",
    "Term" : "36"
   },
    {
    "Date" : "2024-01-01",
    "PmtType" : "PayPrin",
    "Amount" : "1000.00",
    "Term" : "36"
   },
    {
    "Date" : "0000-01-00",
    "PmtType" : "FixedPmt",
    "ReplaceIdx" : "1"
   },
    {
    "Date" : "0000-03-00",
    "PmtType" : "FixedPmt",
    "ReplaceIdx" : "1"
   },
    {
    "Date" : "0000-04-00",
    "PmtType" : "FixedPmt",
    "ReplaceIdx" : "1"
   }
  ]
}

In the example above, the first PmtStream with a PmtType of PayInt has an index of 0, with the PayPrin payment stream having an index of 1, etc.

All three replacement payment streams (with indexes of 2, 3, and 4) indicate that they are targeting the PayPrin payment stream only by specifying "ReplaceIdx" : "1". Also note that once the replacement payments are applied to the applicable payments, those payments will no longer be considered to be a part of the original payment stream, but instead will be considered to be a part of the replacement payment stream that was applied.

Example 2:

Assume we wanted to build a repayment schedule of 24 interest only payments, followed by 36 computed equal payments. Also, assume that we wanted to skip the interest only payments made in December. Then, we could build a request in the following manner:

{
  "PmtStreams" : [
    {
    "Date" : "2024-06-01",
    "PmtType" : "CalcPmt",
    "Term" : "60"
   },
    {
    "Date" : "0001-00-00",
    "PmtType" : "PayInt",
    "Term" : "24"
   },
    {
    "Date" : "0000-12-00",
    "PmtType" : "FixedPmt",
    "ReplaceIdx" : "1"
   }
  ]
}

Above, PmtStreams[0] sets up the basic repayment schedule with 60 computed equal payments. Then, PmtStreams[1] replaces payments 1-24 with interest only payments. Finally, PmtStreams[2] replaces the December payment in the interest only period with a skipped payment.

If you are creating overlapping payment streams with payments that fall on the same day, then we recommend that you set the value of the Merge field of the EditOutput object to false. If Merge is left at its default value of true, merging of payments occurs before replacement payments are enforced, thus making targeting a given payment stream much more difficult if they are merged with a payment from a second payment stream.

🔹 Data.PmtStreams[].SemimonthlyDay

When specifying a semimonthly payment stream, the day number on which the first payment is made determines the day number for all of the following odd numbered payments. If you omit this field or specify a value of 0, then the even numbered payments will be generated using the default method within the SCE.

If you wish to specify the day number on which even numbered payments fall (overriding the default method used in the SCE), then set the value of this field to the desired day number. Setting the value of this field to 31 will cause all even payments to fall on the last day of the month.

As an example, if you want to specify a semi-monthly payment stream beginning on January 1, 2019 with payments that fall on the 1st and 15th of each month for 24 payments, the object should look something like this:

{
  "PmtStreams" : [
    {
      "Date" : "2019-01-01",
      "Term" : "24",
      "PPY" : "24",
      "SemimonthlyDay" : "15"
   }
  ]
}

🔹 Data.PmtStreams[].Term

The term field indicates the the number of payments to be made at the specified payment frequency (see PmtStream.PPY above), after which the payment stream is completed. The default value is 1. If the value of the PmtStream.Date field is not a valid date, then the value of this field is ignored, unless it is a replacement payment using the NNNN-00-00 date format.

🔹 Data.PmtStreams[].Weekends

If payment stream dates (including the specified start Date) are not allowed to fall on a Saturday or Sunday, then set the value of this field to something other than ignore. The meaning of the other three values are defined below:

• prev - The date will be moved to the Friday before the computed weekend date.
• near - The date will be moved to the Friday before the computed weekend date if the computed weekend date falls on a Saturday, otherwise it will be moved to the Monday after.
• next - The date will be moved to the Monday after the computed weekend date.

Note that two other PmtStreams[] fields can cause the computed dates to be adjusted - AllowFeb29 and Holidays. For a complete description of how these three fields work together, please see the documentation for the Holidays field.

🟦 Data.Protection

If the calling application wishes to add any payment protection products to the loan (e.g. credit insurance or debt protection), then this object and at least one Product object in the Products[] array must be present.

Fields: 🔹Protection.DataPath, 🔹Protection.ShowDataPath

Objects: 🟦 Products[]

🔹 Data.Protection.DataPath

If this field is set, the SCE will look for a /data folder containing the setup files in the path specified. Thus, if the DataPath is set to /etc/sce, the SCE will look for the setup files in /etc/sce/data.

If the calling application wishes to specify the data directory path in its entirety (e.g. the calling app does not want the SCE to append /data to the provided path), then simply terminate the specified DataPath with an asterisk (*). Thus, if the DataPath is set to /etc/sce/bank1/*, the SCE will look for the setup files in /etc/sce/bank1/.

If this field is not set, the SCE will attempt to located the /data folder in the default data directory path location, which can be retrieved using the Version module.

This field is useful if you wish to use only a single installation of the SCE, but have many different setup file groupings. By specifying a different DataPath for each grouping, you can easily separate the groups from one another instead of grouping them all together in a single directory.

🔹 Data.Protection.ShowDataPath

This field determines if the data directory path used in the calculation of the loan will be disclosed in the response as a field of the Protection object.

🟦 Data.Protection.Products[]

For each distinct payment protection product that the calling application wishes to add to the loan, a Product object is required.

As an example, if a loan was requested with single decreasing life, single disability, single involuntary unemployment, and joint property insurances, then the input JSON detailing the protection requests would look similar to the following:

{
  "Protection" : {
    "Products" : [
      {
        "Code" : "LI",
        "Birthdays" : [
          "1966-04-16"
        ]
     },
      {
        "Code" : "AH",
        "Birthdays" : [
          "1966-04-16"
        ]
     },
      {
        "Code" : "IU",
        "Birthdays" : [
          "1966-04-16"
        ]
     },
      {
        "Code" : "PP",
        "Birthdays" : [
          "1966-04-16",
          "1969-11-21"
        ]
     }
    ]
 }
}

Fields: 🔹Account, 🔹Benefit, 🔸Birthdays[], 🔸Code, 🔹Coverage, 🔹Dismemberment, 🔹Financed, 🔹Method, 🔹ShowFactor, 🔹Table, 🔹Term, 🔹TermUnits, 🔹UseLevelRates

Objects: None

🔹 Data.Protection.Products[].Account

This field specifies the account number that will be used to define the requested product. Each account is numbered from 1 to 9,999, and each account corresponds to a set of setup file which define numerous settings which define the product and how it is calculated, such as the insurance rates, caps, formulas used, etc. If this field is not specified, a default value of 1 will be used.

🔹 Data.Protection.Products[].Benefit

If you wish to specify a benefit amount less than the maximum allowed, then do so with this field. Omitting this field will ensure that the maximum benefit amount allowed will be used in the loan calculation. Note that if the specified account has not been set up to allow for user-specified benefit amounts for the product in question, or if the product itself does not have the notion of a monthly benefit (such as life and property products), then this field will be ignored.

🔸 Data.Protection.Products[].Birthdays[]

This array contains the date of birth for one or two borrowers requesting a payment protection product. The type of coverage provided (e.g. single or joint) is determined by the number of members in the array. Thus, to request single accident and health coverage, the Product object (with "Code" : "AH") requires a Birthdays[] array with a single birthday element containing the birthday of the borrower seeking coverage. Similarly, to request joint decreasing life coverage, the Product object (with "Code" : "CL") requires a Birthdays[] array with two elements, each of which contains the birthday of a borrower seeking coverage.

Since the type of coverage depends upon the number of elements present in the array, at lease one must appear and no more than two are allowed (as the only coverage options are single or joint).

All dates must be in the form of YYYY-MM-DD, and be 10 characters long.

🔸 Data.Protection.Products[].Code

This field defines the type of payment protection product, and which setup files are references for calculation, rate, and cap purposes. In the description of each product below, "NNNN" is the Account number (see above, an account number of 1 would thus be "0001").

• LI - The requested product is treated as decreasing credit life and will reference the clNNNN.ini setup file.
• AH - The requested product is treated as accident and health and will reference the ahNNNN.ini setup file.
• IU - The requested product is treated as involuntary unemployment and will reference the iuNNNN.ini setup file.
• PP - The requested product is treated as property insurance and will reference the `ppNNNN.ini setup file.

🔹 Data.Protection.Products[].Coverage

If you wish to specify a coverage amount less than the maximum allowed, then do so with this field. Omitting this field will ensure that the maximum coverage amount allowed will be used in the loan calculation. Note that if the specified account has not been set up to allow for user specified coverage amounts for the product in question, then this field will be ignored.

🔹 Data.Protection.Products[].Dismemberment

If the account specified has been set up to offer life protection products with optional dismemberment coverage, and if the optional dismemberment coverage is desired, then set this field's value to true. Otherwise, use the default value of false.

🔹 Data.Protection.Products[].Financed

Single premium protection products are typically financed (added to the principal balance). If you wish to have the premiums paid up front at loan cloasing, then set the value of this field to false.

🔹 Data.Protection.Products[].Method

Some accounts are configured to offer different types of credit life products (usually gross and net). In these accounts, this field allows the calling application to specify which method to use for a given loan. If no method is present in the request, then the default method will be used.

🔹 Data.Protection.Products[].ShowFactor

If this field is set to true, then the Product.Cost response object (member of the Products[] array) will include a Factor field which is useful to J. L. Sherman and Associates when debugging protection calculations.

🔹 Data.Protection.Products[].Table

When requesting the accident and health product (e.g. the Code field is set to AH), if the specified account has been set up with multiple disability or debt cancellation plans, then this field determines which plan number will be used. The value of the Table field must be an integer in [1...20]. If no table number is specified, the first table will be used.

If the requested product Code is not AH, then this field is ignored.

🔹 Data.Protection.Products[].Term`

If you need to specify a coverage term (in months or payments) less than the maximum allowed, then do so using this field. If this field is omitted, then the loan will be covered for the maximum term allowed. Note that if the specified account has not been set up to allow for user specified coverage terms for this product, then this field will be ignored.

🔹 Data.Protection.Products[].TermUnits

The specified numeric coverage term (see Term field, above) will be interpreted as a number of payments or months, depending upon the value of this field.

🔹 Data.Protection.Products[].UseLevelRates

If the account specified has been set up to offer single premium credit life using level rates instead of the normal decreasing rates, and if you wish to use level rates instead of decreasing, then set this field's value to true. Otherwise, use the default value of false.

🟦 Data.TILARESPA2015

If the value of this field is true, then the SCE will include data for the Integrated Mortgage Disclosures under the Real Estate Settlement Procedures Act (Regulation X) and the Truth In Lending Act (Regulation Z) rule, which is required as of August 1st, 2015. If the field is omitted or set to false, then the TILA RESPA outputs will not be generated.

The TILARESPA2015 field may also be passed in as an object, with "TILARESPA2015" : {} equivalent to "TILARESPA2015" : true.

Fields: 🔹MaxPnIDetails, 🔹MinPnIDetails

Objects: None

🔹 Data.TILARESPA2015.MaxPnIDetails

If the loan is an ARM and has a specified a maximum lifetime interest rate (see ARM.Limits.Ceiling), and if the calling application requires the principal and interest breakdown for each MaxPnI payment returned in the amortization schedule, then set the value of this field to true.

Doing so will return MaxInt and MaxPrin fields of the AmLine object associated with each MinPnI payment. object associated with each MaxPnI payment.

🔹 Data.TILARESPA2015.MinPnIDetails

If the loan is an ARM and has specified a minimum lifetime interest rate (see ARM.Limits.Floor), and if the calling application requires the principal and interest breakdown for each MinPnI payment returned in the amortization schedule, then set the value of this field to true.

Doing so will return MinInt and MinPrin fields of the AmLine object associated with each MinPnI payment.