Hcm Module - Request

The fields of the Data object supported by a Hcm 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: 🔸AmountFinanced, 🔸Apr, 🔹DataPath, 🔸Dwelling, 🔹FederalStatePremiums, 🔸FinanceCharge, 🔸InterestCharge, 🔸LienType, 🔸LoanAmount, 🔹LoanOriginatorFees, 🔸LockInDate, 🔹PPY, 🔸RateType, 🔹Term, 🔹TermInYears, 🔹ThirdPartyCharges

Objects: 🟦 CreditInsurance, 🟦 DiscountPoints, 🟦 Format, 🟦 PMI, 🟦 PrepaymentPenalty, 🟦 RealEstate

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

🔸 Data.AmountFinanced

As defined in Regulation Z (Section 1026.18(b)), the amount of credit provided to the borrower or on the borrower's behalf. As an example, the SCE's Loan module returns the loan's Amount Financed in the Data.FedBox.AmtFin field.

🔸 Data.Apr

This field's value contains the APR applicable to the transaction, which is not the same as the Regulation Z APR. The APR applicable to the transaction is determined as follows (from Section 1026.32(a)(3)):

1. If the rate plan is fixed, then the APR equals the interest rate in effect as of the date the interest rate for the transaction is set.
2. If the rate plan varies based on an index, then the APR equals the maximum margin allowed during the term of the loan plus the value of the index rate in effect as of the date the interest rate for the transaction is set.
3. If the rate plan varies and is \emph{not} based on an index (case 2 above), then the APR equals the maximum interest rate tat may be imposed during the term of the loan.

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

If this is a first Lien, then if the dwelling type is personal property and the loan amount is less than fifty thousand, then the rate spread is 8.5%. For all other first lien loans, the rate spread is 6.5%.

🔹 Data.FederalStatePremiums

The value of this element is the sum of all federal and state mortgage insurance premiums and guarantee fees that are included in the Finance Charge (see Section 1026.32(b)(1)(i)(B)).

🔸 Data.FinanceCharge

As defined in Regulation Z (Section 1026.4), the dollar amount that the credit will cost the borrower. As an example, the SCE's Loan module returns the loan's Finance Charge in the Data.FedBox.FinChg field.

🔸 Data.InterestCharge

The value of this field holds the total interest accrued during the term of the loan, assuming the borrower will make all scheduled payments (see Section 1026.32(b)(1)(i)(A)). As an example, the SCE's Loan module returns the loan's Interest Charge in the Data.Moneys.Interest field.

🔸 Data.LienType

The type of lien plays a part in determining the amount over the APOR (called the rate spread) at which time a loan's APR is considered a HCM. For first-lien loans, that value is 6.5% or 8.5% (depending upon the loan amount and dwelling type); for subordinate-lien loans, that value is 8.5%.

🔸 Data.LoanAmount

The Loan Amount is the face amount of the note (i.e., the principal balance).

🔹 Data.LoanOriginatorFees

The value of this field represents all compensation paid directly or indirectly by a consumer or creditor to a loan originator. See Section 1026.32(b)(1)(ii).

🔸 Data.LockInDate

The value of this field holds the date on which the interest rate of the loan was locked in. All dates must be in the form of YYYY-MM-DD, and be 10 characters long.

The lock in date is used to lookup the APOR rate from the appropriate file. Each row of the file begins with a date, and the row which will be used will have a date which is either on the lock in date, or does not preceed it by more than 6 days. Since the rates are updated weekly, there should never be more than six days between the date of the row used and the specified lock in date.

If the SCE can not find a row in the APOR file which is appropriate for use with the specified lock in date, then an error message will be returned informing the calling application.

🔹 Data.PPY

PPY is an abbreviation for "payments per year", and specifies the payment frequency for the initial fixed rate period of the given loan. The default value of 12 will result ina loan with an initial fixed rate period of 12 payments per year. If the loan in question uses a payment frequency for the initial fixed rate period other than monthly, specify it using this field.

🔸 Data.RateType

The APOR is looked up in one of two tables, determined by the loan's rate type. If the loan uses a fixed rate, then the SCE will look-up the APOR from the YieldTableFixed.txt file. If the loan uses a variable or adjustable rate, then the SCE will look-up the APOR from the YieldTableAdjustable.txt file.

🔹 Data.Term

The value of this field holds the number of payments in the initial fixed rate period of the loan. If the loan uses a fixed rate, then this is equal to the total number of payments in the loan term.

Note that the calling application must specify either the Term (and PPY) or TermInYears field (below).

Note that the calling application must specify either the Term and PPY fields (above) or TermInYears.

🔹 Data.TermInYears

The value of this field holds the term of the initial fixed rate period of the loan, in whole years. Valid terms range from 1 year to 50 years, inclusive.

🔹 Data.ThirdPartyCharges

This field holds the sum of all bona fide third-party charges included in the Finance Charge, as defined in Section 1026.32(b)(1)(i)(D).

🟦 Data.CreditInsurance

If credit life, credit disability, credit unemployment, or credit property insurance are included in the loan (or any other life, accident, health, or loss-of-income insurance for which the creditor is a beneficiary), then this object should be included in the request with its fields set as appropriate. See Section 1026.32(b)(1)(iv).

Fields: 🔹Premiums, 🔹FinanceAmt

Objects: None

🔹 Data.CreditInsurance.Premiums

The total of all credit life, credit disability, credit unemployment, or credit property insurance premiums.

🔹 Data.CreditInsurance.FinanceAmt

The value of this field specifies the amount of the above specified premiums and/or fees which were financed.

🟦 Data.DiscountPoints

If a loan features discount points, pass the appropriate data using the fields of this object.

Fields: 🔹Fee, 🔹FullRate, 🔹Points

Objects: None

🔹 Data.DiscountPoints.Fee

The total fee due for the discounted interest rate.

🔹 Data.DiscountPoints.FullRate

The value of this field specifies the non-discounted rate, or the interest rate without any discount.

🔹 Data.DiscountPoints.Points

The value of this field specifies the number of bona fide discount points paid by the borrower. According to Section 1026.32(b)(3)(i)(D), a bona fide discount point "means an amount equal to 1 percent of the loan amount paid by the customer that reduces the interest rate".

🟦 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 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.PMI

Hcm requests which include private mortgage insurance require data to be passed using this object.

Fields: 🔹After, 🔹AtOrBefore, 🔹MaxAllowedAtOrBefore

Objects: None

🔹 Data.PMI.After

This field specifies the private mortgage insurance premiums payable after consummation. See Section 1026.32(b)(1)(i)(C)(1).

🔹 Data.PMI.AtOrBefore

The value of this field represents private mortgage insurance premiums paid at or before consummation. See Section 1026.32(b)(1)(i)(C)(2).

🔹 Data.PMI.MaxAllowedAtOrBefore

The maximum private mortgage insurance premium paid at or before consummation allowable under Section 203(c)(2)(A) of the National Housing Act. See Section 1026.32(b)(1)(i)(C)(2).

🟦 Data.PrepaymentPenalty

If the loan features a prepayment penalty, include this object and its relevant fields.

Fields: 🔹After36Months, 🔹AmountPrepaid, 🔹FinanceAmt, 🔹Max, 🔹Total

Objects: None

🔹 Data.PrepaymentPenalty.After36Months

If, under the terms of the loan contract, the creditor can charge a prepayment penalty more than 36 months after consummation, then the calling application should set the value of this field to true.

Setting this value to true will trigger the prepayment penalty test, and his classify the specified loan as a HCM.

🔹 Data.PrepaymentPenalty.AmountPrepaid

If the maximum prepayment penalty exceeds 2% of this field's value, then the prepayment penalty test will be triggered.

🔹 Data.PrepaymentPenalty.FinanceAmt

The value of this field specifies the amount of the total prepayment penalty which was financed by the creditor.

🔹 Data.PrepaymentPenalty.Max

The maximum prepayment penalty that may be charged or collected under the terms of the mortgage loan. See Section 1026.32(b)(1)(v).

🔹 Data.PrepaymentPenalty.Total

The total prepayment penalty incurred by the consumer if the consumer refinances the existing mortgage loan with the current holder of the existing loan, a servicer acting on behalf of the current holder, or an affiliate of either. See Section 1026.32(b)(1)(vi).

🟦 Data.RealEstate

Please see Section 1026.32(b)(1)(iii) for a discussion of the real estate fees and other charges which should be included here.

Fields: 🔹Fee, 🔹FinanceAmt

Objects: None

🔹 Data.RealEstate.Fee

The total fee due for all appropriate real estate fees and other charges.

🔹 Data.RealEstate.FinanceAmt

The value of this field specifies the amount of the above specified real estate fees and other charges which were financed.