High Cost Mortgage (HCM) - Request

Please see the Legend to understand the conventions used to document each element and attribute. Note that for requests, the XML elements are documented in alphabetical order by parent element.

🟥 <inHCM>

This is the root element of the HCM query input message, and is required. This contains child elements which specify the particulars of the already computed loan which is being examined to see if it is a HCM. The following attributes of the <inHCM> element are defined:

Attributes: 🔹DataDirPath

🔹 DataDirPath

If this attribute is set, the SCEX will look for a data folder containing the APOR and hcm.ini files in the path specified. Thus, in the example above where DataDirPath is set to C:\SCEX\, the SCEX will look for the APOR and hcm.ini files in C:\SCEX\data. Note that the APOR files must be named as follows: YieldTableFixed.txt and YieldTableAdjustable.txt.

If the calling application wishes to specify the data directory path in its entirety (e.g. the calling app does not want the SCEX to append \data to the provided path), then simply terminate the specified DataDirPath with an asterisk (*). Thus, if the DataDirPath is set to C:\SCEX\bank1\*, the SCEX will look for the APOR files in C:\SCEX\bank1\.

If this attribute is not set, the SCEX will attempt to locate the data folder in the default data directory path location, which can be retrieved using the <inVERSION> query, and set via the SCEX API.

Since the APOR and hcm.ini files are global in nature, you only need to have one copy of these files available even if your installation hosts multiple data paths for different clients. The APOR files are identical to those needed for the HIPML module, and thus a single location containing the APOR files can be used for both modules.

🟥 <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 SCEX returns the loan’s Amount Financed under <outLOANTYPE>→<FedBox>→<AmtFin>.

Attributes: None

🟥 <APR>

This element 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 not based on an index (case 2 above), then the APR equals the maximum interest rate that may be imposed during the term of the loan.

Attributes: None

🟦 <CreditInsurance>

Any premiums or other charges payable at or before consummation for any credit life, credit disability, credit unemployment, or credit property insurance, or any other life, accident, health, or loss-of-income insurance for which the creditor is a beneficiary. See Section 1026.32(b)(1)(iv).

Attributes: 🔹FinanceAmt

🔹 FinanceAmt

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

🟦 <DiscountPoints>

This element 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”.

Attributes: 🔹Fee, 🔹FullRate

🔹 Fee

The total fee due for the discounted interest rate.

🔹 FullRate

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

🟦 <FederalStatePremiumsFees>

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).

Attributes: None

🟥 <FinanceCharge>

As defined in Regulation Z (Section 1026.4), the dollar amount that the credit will cost the borrower. As an example, the SCEX returns the loan’s Finance Charge under <outLOANTYPE>→<FedBox>→<FinChg>.

Attributes: None

🟦 <Format>

The <Format> element is one of the first elements parsed from a request, as the attributes of this empty element affect how date and numeric values are parsed and validated.

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

🔹 CurrencyDecimals

When displaying and parsing Currency values, the value of this attribute determines the maximum number of decimal places allowed after the DecimalSeparator.

🔹 DateFormat

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

• YMD - All dates should be formatted as YYYY-MM-DD.
• MDY - All dates should be formatted as MM-DD-YYYY.
• DMY - All dates should be formatted 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 attribute.

🔹 DateSeparator

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

🔹 DecimalSeparator

When displaying and parsing Currency or Decimal numeric values, this attribute determines the character used to separate the fractional part from the whole.

🔹 StrictDP

If the value of this attribute 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 attribute is 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.

🔹 ThousandSeparator

When displaying numeric values, this attribute determines the character used to separate the thousands places from the hundreds. Note that when parsing numeric values, the value of this attribute is ignored.

🟥 <InterestCharge>

This element contains 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 SCEX returns the loan’s Interest Charge under <outLOANTYPE>→<Moneys>→<Interest>.

Attributes: None

🟥 <Lien>

This element itself contains no data. Instead, all of the information used to determine the type of lien is contained in the following attribute of the element:

Attributes: 🔹Dwelling, 🔹Rate, 🔹Type

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

🔹 Rate

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 SCEX will look-up the APOR from the YieldTableFixed.txt file. If the loan uses a variable or adjustable rate, then the SCEX will look-up the APOR from the YieldTableAdjustable.txt file.

🔹 Type

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%.

🟥 <LoanAmount>

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

Attributes: None

🟦 <LoanOriginatorFees>

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

Attributes: None

🟥 <LockInDate>

This element contains 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. Hence, a lock in date of December 29, 2009 would be specified as <LockInDate>2009-12-29</LockInDate>.

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 precede 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 SCEX 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.

Attributes: None

🟦 <PMI>

This element itself contains no data. Instead, all of the information used to specify PMI information is contained in the following attribute of the element:

Attributes: 🔹After, 🔹AtOrBefore, 🔹MaxAllowedAtOrBefore

🔹 After

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

🔹 AtOrBefore

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

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

🟦 <PrepaymentPenalty>

This element itself contains no data. Instead, all of the information used to specify any prepayment penalty information is contained in the following attribute of the element:

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

🔹 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 attribute to true.

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

🔹 AmountPrepaid

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

🔹 FinanceAmt

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

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

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

🟦 <RealEstateFees>

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

Attributes: 🔹FinanceAmt

🔹 FinanceAmt

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

🟦 <Term>

The <Term> element 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> or <TermInYears> element.

Attributes: 🔹PPY

🔹 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 monthly will result in a loan with an initial fixed rate period of 12 payments per year. If the loan in question uses a payment frequency other than monthly, specify it using this attribute.

🟦 <TermInYears>

The <TermInYears> element 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.

Note that the calling application must specify either the <Term> or <TermInYears> element.

Attributes: None

🟦 <ThirdPartyCharges>

This element 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).

Attributes: None