Construction Loan Module - Request

The fields of the Data object supported by a Construction 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, 🔹HalfCommitment, 🔸IntRate, 🔹IntStartDate, 🔸LoanDate, 🔸PmtDate, 🔹PPY, 🔸Proceeds, 🔸Term, 🔹TotalDown

Objects: 🟦 Apr, 🟦 Fees[], 🟦 Format, 🟦 ODI, 🟦 Settings

The fields of the Data object supported by an Equal Pmt module request are defined in alphabetical order below:

🔹 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.Method and Format.CurrencyDecimals fields, as appropriate for the country specified.

🔹 Data.HalfCommitment

During the term of the construction loan, the estimated interest for disclosure purposes may be either computed on the full or half commitment amounts. By setting this field to true, interest will be estimated using half of the initial commitment amount (i.e. the principal balance). The default value of false will cause interest to be estimated using the entire initial commitment amount.

🔸 Data.IntRate

Determine the interest rate used for the loan. The interest rate should be expressed as a percentage. For example, a loan computed with a rate of 5.125% would be specified as "IntRate" : "5.125".

🔹 Data.IntStartDate

This field contains the date on which interest begins to accrue on the loan's principal balance. If this field is not specified, then the interest start date is set equal the loan date. Also note that the interest start date must be equal to the loan date when computing a construction loan.

The interest start date (when specified) must be on or after the loan date, as well as on or before the first payment date.

🔸 Data.LoanDate

This field holds the date on which the loan amount is disbursed and interest begins to accrue. All dates must be in the form of YYYY-MM-DD, and be 10 characters long.

🔸 Data.PmtDate

This field specifies the first (and for single payment notes, only) payment date in the loan's repayment schedule. All dates must be in the form of YYYY-MM-DD, and be 10 characters long.

🔹 Data.PPY

PPY is an abbreviation for payments per year, and determines the payment frequency for the requested loan. The default value of 12 will result in a loan with 12 payments per year. If you require a loan with a payment frequency other than monthly, specify it using this field.

🔸 Data.Proceeds

The proceeds specified indicate the amount of money the borrower is requesting, and does not include financed fees, financed insurances, etc.

🔸 Data.Term

The Term field indicates the the number of payments to be made at the specified payment frequency (see the PPY field above), after which the loan is scheduled to be paid off.

🔹 Data.TotalDown

This optional field represents the total down payment that the borrower has applied to reduce the requested proceeds. It may consist of a cash down payment, net trade-in value, or rebate. You only need to specify a total down payment if the loan needs to disclose a total sale price. Typical examples of these loan types are auto and boat loans.

🟦 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: 🔹MAPR_Max, 🔹Method, 🔹UseMAPR

Objects: None

🔹 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.Method

This field allows the calling application to specify an APR calculation method which will override the default value found in the setup file for the given Account. If this field is set to a valid value, then the specified method will be used to compute the APR for this loan calculation.

If the Country field has been set by the calling application and this field is not set, then the APR method used will be determined by the specified country. For the United States of America, the default APR method is actuarial. For a country in the European Union, the default value is eu (European Union APR). For Canada, the default APR method is ca (Canadian APR).

The xirr value implements the internal rate of return method as implemented in Microsoft\textregistered Excel via the XIRR() function, and is based on an actual day calendar with a 365 day divisor.

The xirr360 value implements the internal rate of return method based upon a unit period calendar with a 360 day divisor.

The irr value implements a common spreadsheet internal rate of return method which assumes strict regular periods. Deviating from a strict regular periodicity may produce unreliable results.

If this field is not specified and the Country field is not specified, then the value of default will be used which informs the SCE to use the APR method defined in the setup file for the specified Account.

🔹 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.Fees[]

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

Fields: 🔹AddToFinChg, 🔹AddToPrin, 🔹Adjust, 🔹CalcType, 🔹Entry, 🔹IsLoanCost, 🔹MAPR, 🔹Max, 🔹Min, 🔹Name

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",
      "Entry" : "0.115",
      "AddToPrin" : true,
      "AddToFinChg" : false
    }
  ]
}

🔹 Data.Fees[].CalcType

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

🔹 Data.Fees[].Entry

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

🔹 Data.Fees[].IsLoanCost

When requesting TILA RESPA outputs (via the Settings.TILARESPA2015 field), the SCE needs to know which fees need to be considered "borrower paid loan costs", as defined in the rule. Please note that if the fee is paid by a lender or other third party, then the fee does not affect the loan calculation and should not be sent to the SCE. If it is sent, then the value of this field should be set to false.

🔹 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.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.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, 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.Settings

The Settings object allows the calling application to alter the default loan calculation options.

Fields: 🔹Account, 🔹AccrualCode, 🔹ConAccrual, 🔹ConMethod, 🔹ConUnitPeriodDivisor, 🔹DataPath, 🔹Lastday, 🔹PmtRound, 🔹ShowAmTable, 🔹TILARESPA2015, 🔹YieldPPY

Objects: None

🔹 Data.Settings.Account

The Account field specifies the numeric setup file account number that will be used to compute the requested loan. Each account is numbered from 1 to 9,999, and each account corresponds to a set of setup file which define numerous settings which may affect the loan calculation, such as the accrual method, insurance methods / rates / caps, etc.

🔹 Data.Settings.AccrualCode

The method of interest accrual is defined by this field. A value of default informs the SCE to use the interest accrual method defined in the setup file for the specified Account. All other valid accrual codes are described in the table below.

🔹 Data.Settings.ConAccrual

If the loan request is a construction loan where interest is computed using the Simple method (see Settings.ConMethod), then this field allows the calling application to specify the simple accrual method used.

A value of default indicates that the accrual method used will be that which is specified in the setup files for the given account. unitperiod computes interest on a pure unit period basis, with odd days optionally taken into account (see Settings.ConUnitPeriodDivisor field below for more information). actual360 uses an actual day calendar and divides the day count by 360 to determine the appropriate interest factor. actual365 does the same thing, but uses a 365 divisor instead.

🔹 Data.Settings.ConMethod

When computing a construction loan, there are two supported methods for computing interest during the constrcution period:

If the value of this field is simple, then the estimated construction interets will be computed and disclosed as a lup-sum prepaid fee (see the Moneys.ConstructInterest response field).

If the value of this field is interestonly, then the construction and permanent loans are combined into a single loan, with the construction (and permanent) loan's interest being reflected in the Moneys.Interest field, and both loans reflected in a single, combined amortization schedule.

A value of default instructs the SCE to use the construction method specified in the setup file for the given account.

🔹 Data.Settings.ConUnitPeriodDivisor

When specifying a Settings.ConAccrual field value of unitperiod (see above), this field allows the calling application to specify how odd days between the loan and first payment dates are taken into account.

🔹 Data.Settings.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.Settings.Lastday

If present, this field overrides the Last Day setting in the setup files, which only applies to loans computed with an actual day accrual calendar where the first payment date falls at the end of a month with fewer than 31 days. As an example, if the first payment date is on April 30, should the following payment dates be made on the 30th of each month, or on the last day of the month?

If no value is specified for this field, then the setup file setting will be used. If true is specified, then conditions triggering a last day situation will result in payments which fall at the end of the month. A value of false indicates that when dictated, subsequent payment dates will not be moved to the last day of the month.

🔹 Data.Settings.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. default means that the setting should be configured as specified in the setup file.

🔹 Data.Settings.ShowAmTable

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

🔹 Data.Settings.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.

Note that this field is supported for equal payment loans, balloon payment loans, single payment notes, interest only loans, fixed principal plus interest loans, skips, pickups and irregulars, and ARMs.

🔹 Data.Settings.YieldPPY

Canadian mortgages may compute periodic interest using a fractional power of a periodic yield. If set to a value other than `0', this field 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.