Adjustable Rate Mortgage - 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.

🟥 <inARM>

This element is the root element for the request. It is a parent element that has no data, but does have several attributes that offer a wide variety of adjustments.

Attributes: 🔹Account, 🔹AccrualCode, 🔹AprType, 🔹CalcType, 🔹Country, 🔹DataDirPath, 🔹ForceReload, 🔹HideAmort, 🔹Lastday, 🔹MAPR_Max, 🔹Metavante, 🔹OddFinal, 🔹PmtDollarRound, 🔹PmtRound, 🔹PPY, 🔹UseMAPR, 🔹YieldPPY

🔹 Account

This attribute specifies which account should 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 files which define numerous settings which may affect the loan calculation, such as the accrual method, insurance methods and rates, etc. If this attribute is not specified, a default value of 1 will be used.

🔹 AccrualCode

This property allows an accrual method to be used other than the accrual method dictated by the setup file for the given account. If no accrual code attribute is specified, the method defined in the setup file will be used. The Accrual Code Table lists all valid accrual codes available. Note that for the split rate accrual codes (i.e. those above 500), the split rate tiers must be defined in the setup file.

🔹 AprType

This attribute 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 attribute is set to a valid value, then the specified method will be used to compute the APR for this loan calculation.

If the Country attribute has been set by the calling application and this attribute 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).

• default - Use setup file value.
• actuarial - Appendix J Actuarial APR
• usrule - US Rule APR
• eu - European Union APR
• ca - Canadian APR
• xirr - Extended Internal Rate of Return (same as excel function)
• xirr360 - XIRR using a 360 divisor rather than a 365 divisor
• irr - Simple Internal Rate of Return (same as excel function)

If this attribute is not specified and the Country attribute 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.

🔹 CalcType

This attribute specifies how the payment stream is adjusted for rate changes during the term of the loan. If this attribute holds a value of Payments, then the disclosed payment will change with each rate change. A value of Balloon indicates that the payment computed for the teaser term will be used for all but the last payment, with the final payment equal to the amount needed to pay off the loan.

🔹 Country

This attribute 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 Country Codes Table for the list of supported countries and their associated codes.

Currently, the country code is used to determine the default value of the AprType attribute (see above).

🔹 DataDirPath

If this attribute is set, the SCE will look for a data folder containing the setup files in the path specified. Thus, if the DataDirPath is set to C:\SCEX\, the SCE will look for the setup files in C:\SCEX\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 DataDirPath with an asterisk (*). Thus, if the DataDirPath is set to C:\SCEX\bank1\*, the SCE will look for the setup files in C:\SCEX\bank1\.

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

This attribute 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 DataDirPath for each grouping, you can easily separate the groups from one another instead of grouping them all together in a single directory.

🔹 ForceReload

The SCE caches setup files previously used. This improves performance for subsequent loan requests using one of the cached accounts. However, if you need the SCE to reload the setup files for a given request (e.g. you just copied over new setup files), then you can set this attribute to true and the setup files will be forced to reload. If left at the default value of false, then setup files are only reloaded when the SCE notices that one of the setup files has been modified.

🔹 HideAmort

This attribute determines whether or not an amortization schedule will be included in the response, given a successful loan calculation. If you do not require the use of the amortization schedule, then setting this attribute to true will suppress its output. The default value of false will return the amortization schedule as part of the response.

🔹 Lastday

If present, this attribute overrides the Last Day setting in the setup files, which only applies to loans computed with an actual day interest 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 attribute, 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.

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

🔹 Metavante

If this attribute is set to a value of true, then the <Metavante> element will be included in the response. Also, some loans will also disclose <MinInterestPmt> and <MaxInterestPmt> elements.

🔹 OddFinal

This attribute allows the calling application to specify an odd final payment calculation method which will override the default value found in the setup file for the given account. If not specified, then the value of default will be used.

Odd final payments are sometimes desired to produce perfect amortization (i.e. an ending balance of zero after the final payment is made).

🔹 PmtDollarRound

Payments are normally rounded to the penny, according to the method specified by the PmtRound attribute (see below). If the payment should be rounded to the dollar instead of the penny, then set the value of this attribute 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.

🔹 PmtRound

This attribute allows the calling application to specify a payment rounding option which will override the value found in the setup file. If not specified, then the value of default will be used.

• default - Use method specified in setup file.
• nearest - Round computed payment to the nearest penny, using 5/4 rounding. e.g. 300.242 = 300.24, 300.245 = 300.25.
• up - Round computed payment up to the next penny. e.g. 300.241 = 300.25.
• down - Round computed payment down to the previous penny. e.g. 300.249 = 300.24.
• best - Once the unrounded payment has been computed, amortize the loan using the rounded down and rounded up payment, and then return the payment which amortizes the loan’s ending balance closest to zero.

🔹 PPY

PPY is an abbreviation for payments per year, and as one might surmise, determines the payment frequency for the loan. The default value of monthly 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 attribute.

^* Semimonthly loans are characterized by making two payments per month on the same days. A common semimonthly schedule is to make payments every 1st and 16th of the month. Another common schedule is the 15th and the end of every month.

🔹 UseMAPR

If this attribute is set to a value of true, the SCE will compute the Military APR in addition to the Regulation Z APR. The <MAPR> element will be included in the XML loan response.

🔹 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 attribute with a value other than zero, the calling application must include an odd days prepaid fee in the request.

🟦 <AmortTerm>

To specify a balloon payment for the ARM loan using a specified amortization term (similar to an <inBALLOON_SPECIFY_AMORT> request), then set the contents of this element to a value greater than that found in <Term>.

Attributes: None

🟥 <AnnualRateIncrease>

Just how much the interest rate increases when a rate increase is due depends upon this element, in conjunction with the <TermStep> element. In our sample request the annual rate increase is specified as 2%, with rate adjustments every 12 monthly payments. Thus, each rate adjustment will see the interest rate increase by 2%.

Attributes: None

🟦 <ARM_Tweaks>

This optional element itself contains no data. Instead, all of the information used to "tweak" various ARM loan settings is contained in the following attributes of the element.

Attributes: 🔹ForceTeaserSegment, 🔹StarStepDown

🔹 ForceTeaserSegment

If the ARM loan has a constant rate over the term of the loan, should the teaser term portion of the loan be disclosed as a separate payment stream?

🔹 StarStepDown

If the final rate is less than the teaser rate, a value of false will keep the 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, then set the value of this attribute to true. A default value instructs the SCE to use the value stored in the setup file.

🟦 <Construction>

Include the <Construction> element to configure a construction period on a loan. The use of this element requires setup files configured to support construction loans, or specification of the Method to be used. If the specified account is not set up to support construction loans, this element will be ignored.

Attributes: 🔹Accrual, 🔹Active, 🔹HalfCommitment, 🔹Method, 🔹PermanentAttached, 🔹PPY, 🔸Rate, 🔸Term, 🔹UnitOddDayDivisor

🔹 Accrual

If the loan request is a construction loan with no permanent loan attached, this attribute allows the calling application to specify the accrual method used.

• default - The setup files determine the default value for interest accrual.
• unitperiod - Compute periodic interest using a 1/PPY factor.
• actual360 - Compute periodic interest using the actual # of days between payments/360.
• actual365 - Compute periodic interest using the actual # of days between payments/365.

🔹 Active

If this loan request includes a construction loan, then set this attribute to true. If no construction loan is desired, either do not specify the <Construction> element or set this attribute to false.

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

🔹 Method

There are three methods used to define how construction loans are computed and disclosed. A method of default tells the SCE to use the method configured in the setup file. The meaning of the three methods are as follows:

• simple - Compute an aggregate construction interest amount for the entire construction period for both pure construction loans and construction to permanent loans.
• laserpro - Compute an aggregate construction interest amount for the entire construction period for pure construction loans. For construction to permanent loans, compute and disclose discrete interest-only payments during the construction period.
• intonly - Compute and disclose discrete interest-only payments during the construction period for both pure construction loans and construction to permanent loans.

🔹 PermanentAttached

Construction loans may be computed on their own, or they may be attached to a permanent loan which begins at the conclusion of the construction loan. If a permanent loan is attached to the construction loan, then set this attribute’s value to true and set up the permanent loan information in the request elements.

The default value of false indicates that this is solely a construction loan with no permanent attached. In this case, you still need to set up the <LoanDate>, <PmtDate> and <Proceeds> elements.

🔹 PPY

The PPY attribute allows the calling application to specify the payment frequency during the construction period. The default value of monthly will result in a construction loan with 12 payments per year. If you require a payment frequency during the construction period other than monthly, then specify it using this attribute. Note that if a permanent loan is attached to the construction loan, that the permanent loan's payment frequency may differ from the construction period’s payment frequency.

🔸 Rate

This attribute determines the rate applied to the appropriate commitment amount during the term of the construction loan.

🔸 Term

The term of the construction loan (in payments) is specified using this attribute. Please note that the term may not exceed five years.

^* 60 is the maximum number of months in the Construction period. In general, the maximum entry is 5 * PPY, where the PPY is the payments per year attribute of the <Construction> element.

🔹 UnitOddDayDivisor (enum, [], Ignore)

When specifying an Accrual method of type unitperiod, this attribute allows the calling application to specify how odd days between the loan and first payment dates are taken into account.

ignore means that all odd days are ignored, and the calculation will assume one full unit period. 360 and 365 will compute the actual number of days between the loan date and first payment date, and then use either a 360 or 365 divisor to determine the amount of interest accrued during that period. vardpy accrues interest in the same manner as accrual code 250/350.

🟦 <Fee>[]

Unlike most other elements, any number of fees may be defined, or none at all. All of the information used to compute a fee is contained in its attributes.

Attributes: 🔹AddToFinChg, 🔹AddToPrin, 🔹Adjust, 🔹CalcType, 🔸Entry, 🔹IsLoanCost, 🔹MAPR, 🔹MaxValue, 🔹MinValue, 🔹Name

🔹 AddToFinChg

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

🔹 AddToPrin

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

🔹 Adjust

The optional attribute Adjust 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 attribute 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 SCEX is as follows:

<Fee CalcType="OnAmtFin" Entry="0.115" Adjust="-2000" AddToPrin="true" AddToFinChg="false" />

🔹 CalcType

The value of this attribute determines how the fee is to be computed, as described below:

• Dollar - The Entry attribute is understood as a flat dollar amount.
• OnProceeds - The Entry attribute is understood as a percentage value, to be applied to the loan’s proceeds. An Entry of 1.0 would represent a fee of 1.0% of proceeds.
• OnAmtFin - The Entry attribute is understood as a percentage value, to be applied to the Amount Financed. An Entry of 0.5 would represent a fee of 0.5% of Amount Financed.
• OnPrin - The Entry attribute is understood as a percentage value, to be applied to the loan’s principal balance. An Entry of 0.125 would represent a fee of 0.125% of principal balance.
• DocStamp - The Entry attribute is understood as a Florida doc stamp rate, to be applied to the loan’s principal balance. An Entry of 0.35 would represent a fee of 0.35% of the principal balance. You must set the AddToFinChg attribute to false, otherwise the doc stamp fee will return a value of zero.

🔸 Entry

The Entry is the basic starting point fee value that determines the dollar value of the resulting fee computation. How this attribute is interpreted depends upon the CalcType attribute, described above. This value is either a dollar value or a percentage (aka "points").

🔹 IsLoanCost

When requesting the new TILA RESPA outputs (via the <TILARESPA2015> element), 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 attribute should be set to false.

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

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

🔹 MaxValue

If a maximum value for the fee is specified and is greater than zero, then if the computed fee exceeds this maximum value, then this 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 attribute is applied to all fee types documented.

🔹 MinValue

If a minimum value for the fee is specified and is greater than zero, and if the Entry attribute holds a value greater than zero, then if the computed fee is less than this minimum value, then this 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. If a specified minimum value exceeds a specified maximum value, then the minimum value will be ignored. Please note that this attribute is applied to all fee types documented.

🔹 Name

This attribute is for convenience purposes only, and does not affect the calculation of the fee in any manner. If a Name attribute is specified for the <Fee> element, then the corresponding <Fee> element in the XML output will have a Name attribute with the same value. This allows you to easily differentiate fees in the response.

🟦 <FirstRateIncrease>

If the value contained in this element is greater than zero and less than or equal to ten, then the first rate adjustment (which occurs at the conclusion of the teaser term) for the first <TermStep> number of payments will be in this amount. After that, the rate will adjust as described in <AnnualRateIncrease>. Note that this adjustment is always from the teaser rate towards the sum of the specified <Index> and <Margin>. Thus, if the sum of the index and margin is greater than the teaser rate, then the teaser rate will increase by the specified value. Similarly, if the sum of the index and margin is less than the teaser rate (and if rates are allowed to stair step down [see the <ARM_Tweaks> element]), then the rate will decrease by the specified value.

Note that the calling application may specify either the <FirstRateIncrease> or the <PostTeaserRate>, but not both.

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.

🟥 <Index>

This element holds the current value of the rate index at loan closing. When added together with the <Margin>, it produces the target interest rate to adjust towards after the <TeaserTerm> has expired.

Attributes: None

🟦 <InterestPmtRate>

If this loan has interest only payments preceding the ARM loan (i.e. the value contained in <InterestPmts> is greater than zero), then this element contains the interest rate charged during the interest only payment stream unless the interest only payments are configured to use the rates dictated by the ARM rate schedule (see Blended).

If no interest only payments precede the ARM loan, or if the interest only payments are configured to use the rates dictated by the ARM rate schedule (see Blended), then this element may be omitted.

Attributes: None

🟦 <InterestPmts>

If present, this element determines the number of interest only payments made at the start of the ARM loan. After the specified number of interest only payments are made, then the loan continues with principal and interest payments. If this element is not present in the request, then no interest only payments will precede the ARM loan calculation.

Attributes: None

🔹 Blended

Blended interest only payments do not consider the initial stream of interest payments to be outside the scheme of rate increases. For example, if the Blended attribute is set to true with <InterestPmts> specified as 12 and the <TeaserTerm> is set to 48, then the payment stream resulting will be 12 interest only payments followed by 36 principal and interest payments (and the rest of the tiered P&I payments). If the Blended attribute was set to false, then the payment stream would be 12 interest only payments followed by 48 P&I payments at the teaser rate, etc.

If the Blended attribute is set to true, then the <InterestPmtRate> element is ignored. Please note that blended interest only payments are not allowed with ARM loans computed using a CalcType of Balloon.

🟦 <IntStartDate>

This element contains the date on which interest begins to accrue on the loan’s principal balance. If this element is not specified, then the interest start date is defaulted to be the <LoanDate>. 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 <PmtDate>. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, an interest start date April 27, 2024 would be specified as:

<IntStartDate>2024-04-27</IntStartDate>

Attributes: None

🟥 <LoanDate>

This element determines when interest begins to accrue. If interest begins on a later date, use the <IntStartDate> element to define the date on which interest begins to accrue.

This element contains 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. Hence, a loan date of March 4, 2024 would be specified as:

<LoanDate>2024-03-04</LoanDate>

Attributes: None

🟦 <Margin>

This element is closely tied to the <Index> element, and represents the difference between the target interest rate and index rate. The lender determines the margin at the time of loan closing, and it remains fixed for the duration of the loan.

Attributes: 🔹UseAsMin

🔹 UseAsMin

If a <MinRate> element is not present in the request and the value of this attribute is set to true, then the value of the <Margin> element will be treated as a specified minimum rate for all purposes, including the TILA RESPA 2015 disclosures.

🟦 <MaxRate>

This optional element allows the calling application to specify an absolute interest rate maximum during the term of the ARM. If the interest rate ever exceeds this rate maximum, then it will be capped at this value. If left unspecified (or zero), then no absolute rate maximum will be checked.

Note that there are three different ways to specify interest rate maximums:

1. <Index> + <Margin>
2. <TeaserRate> + <MaxRateIncrease>
3. <MaxRate>

Attributes: 🔹ExemptPostTeaser, 🔹ExemptTeaser

🔹 ExemptPostTeaser

This attribute determines whether or not the post teaser rate (if one has been specified) is excluded from the maximum rate constraint. If the value of this attribute is set to true, then the post teaser rate may be greater than the specified maximum rate. If the value of this attribute is set to false, then the rate during the post teaser term can not be greater than the specified maximum rate.

🔹 ExemptTeaser

This attribute determines whether or not the teaser rate is excluded from the maximum rate constraint. If the value of this attribute is set to true, then the teaser rate may be greater than the specified maximum rate. If the value of this attribute is set to false, then rate during the teaser term can not be greater than the specified maximum rate.

🟦 <MaxRateIncrease>

This optional element allows the calling application to specify a maximum value that the interest rate may increase from the specified teaser rate, during the term of the loan. If an interest rate adjustment would exceed the maximum rate increase, then the interest rate will be capped at a value equal to the teaser rate plus the maximum rate increase. If left unspecified (or zero), then no maximum rate increase will be checked.

Attributes: None

🟦 <MinRate>

The contents of this optional element allow you to specify a minimum interest rate for the ARM. Should the interest rate ever dip below this value, then the minimum rate specified will be used instead. If left unspecified (or zero), then no rate minimum will be checked.

Attributes: 🔹ExemptPostTeaser, 🔹ExemptTeaser

🔹 ExemptPostTeaser

This attribute determines whether or not the post teaser rate (if one has been specified) is excluded from the minimum rate constraint. If the value of this attribute is set to true, then the post teaser rate may be less than the specified minimum rate. If the value of this attribute is set to false, then the rate during the post teaser term can not be less than the specified minimum rate.

🔹 ExemptTeaser

This attribute determines whether or not the teaser rate is excluded from the minimum rate constraint. If the value of this attribute is set to true, then the teaser rate may be less than the specified minimum rate. If the value of this attribute is set to false, then the rate during the teaser term can not be less than the specified minimum rate.

🟦 <Mortgage_Insurance>

The <Mortgage_Insurance> element determines if this loan includes one of the supported types of mortgage insurance (MI) - PMI or FHA. This element contains child elements which further specify mortgage insurance options.

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

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

🔹 CashDown

The CashDown attribute 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.

🔹 LoanAmt

The LoanAmt attribute 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.

🔹 PropertyValue

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

🔹 Type

This attribute determines the type of mortgage insurance to include with the loan. If the Type attribute is set to FHA, 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.

🟥 <Mortgage_Insurance>→<MI_Rate>[]

The value of this element specifies the cost of mortgage insurance per $100 of the loan amount. Note that there may be more than one <MI_Rate> element defined in an XML loan request (see the Switch attribute below).

As an example, a loan computed with a MI rate of $1.50 per $100 would be specified as <MI_Rate>1.50</MI_Rate>.

Attributes: 🔸Switch

🔹 Switch

This optional attribute 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 attribute. Single rate example (use a rate of $1.50 for the entire term of MI coverage):

<MI_Rate>1.50</MI_Rate>

Multiple rate example (use a rate of $1.50 for the first 10 years, with a rate of $0.20 for coverage beyond 10 years):

<MI_Rate>1.50</MI_Rate>
<MI_Rate Switch="120">0.20</MI_Rate>

🟦 <Mortgage_Insurance>→<Periodic>

The value of this element represents the term beyond which MI is no longer included. As an example, if mortgage insurance must be removed after the 180th payment, then the calling application should specify <Periodic>180</Periodic> in the XML loan request. 0 means no term removal is in effect.

Attributes: 🔹DropLTV, 🔹WarnLTV

🔹 DropLTV

The value of this attribute 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".

🔹 WarnLTV

The value of this attribute 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".

🟦 <Mortgage_Insurance>→<UpFront>

This element determines the up front fee for mortgage insurance, as disclosed in the <PMI_Fee> element in the results. If this element is not specified, 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 element can be omitted or set to zero.

The following attributes define how the fee is computed and disclosed.

Attributes: 🔹Paid, 🔹Units

🔹 Paid

If the value of this attribute 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 a Pocket Fee that is not added to either the principal balance nor the finance charge.

🔹 Units

If the Units attribute is set to Months, the value of the <UpFront> element represents the number of periodic MI premiums to be paid at closing.

If the Units attribute is set to Years, the value of the <UpFront> element 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 attribute is set to Points, the value of the <UpFront> element represents the percentage of principal to be paid up front. As of October 3, 2011, FHA loans use points.

🟦 <OddDaysPrepaid>

If odd days interest should be treated as a prepaid finance charge or added to the first payment, then include this empty element in the request. The attributes of this element determine how odd days interest is computed and handled.

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

🔹 AccrualCode

The accrual code defines how the odd days interest is computed.

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.

🔹 AddToPmt

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

🔹 AddToPrin

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

🔹 AnchorDate

The computed number of odd days is the number of days between the loan date and the anchor date. This attribute determines how to arrive at the anchor date.

• BackUnitPeriod - The anchor date is one unit period prior to the specified first payment date.
• BackDaysPerPeriod - 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.

🔹 ForceUnitPeriod

If the loan's interest accrual is unit period, this attribute forces the period to the first payment to be 1/12 (or 1/(PmtsPerYear) in general). Without this attribute an accrual code of 202 (Unit Period /365) would use a factor of Days/365 rather than the expected 1/12.

🔹 NoCap

When an odd days interest fee is present and financed, the value of this attribute determines if the ODI fee is added to the principal balance for the purposes of computing the ODI fee (e.g. if it is capitalized). If this value is true, the ODI is computed on the true principal balance less the ODI; false means "compute ODI on the true principal balance.

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

🔹 UseNegODI

If there are negative odd days in the loan, then the value of this attribute determines if a negative odd days interest fee is computed. If the value of this attribute is false, then negative odd days fees are not allowed, the SCEX 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 an odd days interest credit) when there are negative odd days in a loan.

🟥 <PmtDate>

This element contains the date on which the first payment of the loan is made, and must be on or after the loan date.

All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, a first payment date of April 4, 2024 would be specified as:

<PmtDate>2005-04-04</PmtDate>

Attributes: None

🟦 <PostTeaserRate>

Instead of specifying a first rate adjustment using the <FirstRateIncrease> element, the calling application can instead specify an interest rate that applies following the teaser term. This will allow for loans with a teaser rate, followed by a post teaser rate less than the teaser rate, which will then adjust to the sum of the index and margin greater than the teaser rate.

Note that the calling application may specify either the <FirstRateIncrease> or the <PostTeaserRate>, but not both.

Attributes: None

🟥 <Proceeds>

The proceeds specifies the amount the customer has frequested to borrow, ignoring every other financed quantity. Proceeds of up to one billion dollars are accepted.

The amount should be expressed as a number. For example, a request including <Proceeds>10000.00</Proceeds> indicates an amount requested of 10,000.

Attributes: None

🟦 <Protection>

The <Protection> element is used to specify debt protection coverages such as life, disability, involuntary unemployment, personal property and debt cancellation. Each type of coverage is specified by its own sub-element, along with the borrower birthdays. The following attributes apply to this element:

Attributes: 🔹FinanceProt, 🔹LineOfCredit, 🔹Mandatory, 🔹ShowBorrowerInfo, 🔹ShowCaps

🔹 FinanceProt

If the computed premiums for single premium debt protection products should be financed along with the proceeds, then this attribute should be set to true (which is the default value if not specified). A value of false indicates that the computed premiums will not be financed with the proceeds, and hence will be paid out of pocket by the borrower. Note that this applies to single premium insurance products only!

🔹 LineOfCredit

If this is an account using TruStage’s MOB insurance, and if this loan is a line of credit where product term caps should be ignored, then set this attribute to true. Otherwise, leave this attribute unspecified or set it to false.

🔹 Mandatory

If the value of this attribute is set to true, then any computed payment protection premium or fee will be considered a mandatory fee which will be included as a part of the Regulation Z Finance Charge, and hence affect the Regulation Z APR. In this case, the <Protection> element in the response will contain a Mandatory="true" attribute indicating this.

If the Mandatory attribute is set to false, the loan will treat any premiums / fees as normal.

🔹 ShowBorrowerInfo

If the calling application would like to have data returned for each specified borrower instead of a single <CovTerm> element, then set the value of this attribute to true. Otherwise, leave this attribute unspecified or set it to false. See the <Borrower> and <CovTerm> elements defined in the response for more information.

🔹 ShowCaps

If the calling application would like to have cap information (e.g., maximum terms, coverage amounts, ages, etc.) returned for each product offered, set the value of this attribute to true. Otherwise, leave this attribute unspecified or set it to false. See the <Caps> element for more information.

🟦 <Protection>→<Birthday1>

This element contains the date of birth for the primary borrower. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, a birthday of April 9, 1972 would be specified as <Birthday1>1972-04-09</Birthday1>. Note that this element must be set if the Covers attribute of any of the four debt coverage elements is set to borrower1 or both.

Attributes: None

🟦 <Protection>→<Birthday2>

This element contains the date of birth of the secondary borrower. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, a birthday of May 21, 1969 would be specified as <Birthday2>1969-05-21</Birthday2>.

Attributes: None

🟦 <Protection>→<Disability>

The <Disability> element determines what type of disability coverage is requested for the loan. It also serves double duty as the debt cancellation coverage element, for accounts set up to compute debt cancellation using the disability tables. The element itself is empty, with all information needed for disability coverage request being specified in the following attributes:

Attributes: 🔹Benefit, 🔹Covers, 🔹CovTerm, 🔹Table

🔹 Benefit

If you wish to specify a benefit amount less than the maximum allowed, then do so with this attribute. Leaving this attribute unspecified will assure 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, then this attribute will be ignored.

🔹 Covers

This attribute determines what type of coverage is being requested on the loan. The values borrower1 and borrower2 represent single coverage on the appropriate borrower (whose birthdays are contained in the appropriate <Birthday> elements). A request for joint coverage on both borrowers is indicated by a value of both. Finally, if no coverage is desired, specify a value of none or omit the <Disability> element entirely.

🔹 CovTerm

If you need to specify a coverage term (number of payments) less than the maximum allowed, then do so using this attribute. Leaving this attribute unspecified will assure that the loan is covered for the maximum term allowed. Note that if the specified account has not been set up to allow for user specified coverage terms, then this attribute will be ignored.

🔹 Table

If the specified account has been set up with multiple disability or debt cancellation plans, then this attribute determines which plan number will be used. If no table number is specified, the first table (table zero) will be used. To find out the number of available plans, use the <AhSetCount> element in the <inINPUT_TOOL> response.

🟦 <Protection>→<Life>

The <Life> element determines what type of life coverage is requested for the loan. The element itself is empty, with all information needed for a life coverage request being specified in the following attributes:

Attributes: 🔹Coverage, 🔹Covers, 🔹CovTerm, 🔹Dismemberment, 🔹Method, 🔹UseLevelRates

🔹 Coverage

If you wish to specify a benefit amount less than the maximum allowed, then do so with this attribute. Leaving this attribute unspecified will assure 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, then this attribute will be ignored.

If you wish to specify a coverage amount less than the maximum allowed, then do so with this attribute. Leaving this attribute unspecified will assure 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, then this attribute will be ignored.

🔹 Covers

This attribute determines what type of coverage is being requested on the loan. The values borrower1 and borrower2 represent single coverage on the appropriate borrower (whose birthdays are contained in the appropriate <Birthday> elements). A request for joint coverage on both borrowers is indicated by a value of both. Finally, if no coverage is desired, specify a value of none or omit the <life> element entirely.

🔹 CovTerm

If you need to specify a coverage term (number of payments) less than the maximum allowed, then do so using this attribute. Leaving this attribute unspecified will assure that the loan is covered for the maximum term allowed. Note that if the specified account has not been set up to allow for user specified coverage terms, then this attribute will be ignored.

🔹 Dismemberment

If the specified account has been set up to offer optional dismemberment coverage to be offered with life coverage (using an increased rate in the premium calculation), then this attribute determines whether or not this additional coverage will be provided.

🔹 Method

If the specified account has been set up to offer single premium life coverage by default, net or gross coverage, then this attribute can be used to specify which type of coverage to compute with the loan. For all other accounts, the default value of default should be used (or simply do not specify the attribute at all).

🔹 UseLevelRates

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

🟦 <Protection>→<Unemployment>

The <Unemployment> element determines what type of involuntary unemployment coverage is requested for the loan. The element itself is empty, with all information needed for a coverage request being specified in the following attributes:

Attributes: 🔹Benefit, 🔹Covers, 🔹CovTerm

🔹 Benefit

If you wish to specify a benefit amount less than the maximum allowed, then do so with this attribute. Leaving this attribute unspecified will assure 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, then this attribute will be ignored.

🔹 Covers

This attribute determines what type of coverage is being requested on the loan. The values borrower1 and borrower2 represent single coverage on the appropriate borrower (whose birthdays are contained in the appropriate <Birthday> elements). A request for joint coverage on both borrowers is indicated by a value of both. Finally, if no coverage is desired, specify a value of none or omit the <Unemployment> element entirely.

🔹 CovTerm

If you need to specify a coverage term (number of payments) less than the maximum allowed, then do so using this attribute. Leaving this attribute unspecified will ensure that the loan is covered for the maximum term allowed. Note that if the specified account has not been set up to allow for user-specified coverage terms, then this attribute will be ignored.

🟦 <RoundRate>

If the value of this element is greater than zero, then the sum of the specified index and margin (i.e. the sum of the unrounded values specified in the request) will be rounded according to this value and the Round attribute defined below.

As an example, if the sum of the specified index and margin is 5.01 and the value of this element is 0.125 (1/8th of a percent), then the computed index + margin will be rounded to either 5.0 or 5.125 depending upon the value of the Round attribute specified.

If no value is specified for this element, then no rounding of the index plus margin (nor any other rates) will occur.

Attributes: 🔹Round

🔹 Round

If a value is specified for the <RoundRate> element, then the value of this attribute determines how the rounding will be performed.

🟥 <TeaserRate>

The teaser rate is the interest rate initially applied to the loan. These rates are in effect for a given number of payments (see <TeaserTerm> below), after which regular rate adjustments will take place during the life of the loan.

Attributes: None

🟥 <TeaserTerm>

This element specifies the number of payments that the <TeaserRate> is in effect. No interest rate increase will take place during the teaser term.

Attributes: None

🟥 <Term>

The value of this element indicates the number of payments in the loan.

The term must be entered as a number of payments, not a duration of time. Therefore, <Term>72</Term> represents 72 payments, not 72 months (or years). This term is intimately tied to the PPY (# of payments per year) attribute of the root element. If the value of the PPY attribute was 24 (semimonthly) for this loan, the 72 payments would mean that the duration of the loan is three years, since years = number of payments / payments per year = 72 / 24 = 3.

^* In general, the term can be no greater than 50 years, so the maximum entry would be 50 * PPY. Weekly loans, however, are limited to 30 years, or 1,560 payments.

Attributes: None

🟥 <TermStep>

This element specifies the number of payments between interest rate increases after the teaser term has passed. In our sample request the teaser term is 12 months, with a term step of 12 months. This means that the first 12 months will use the teaser rate as the interest rate. Then, the next 12 months will use an increased rate, with the next 12 months increasing the rate again, etc.

If the value of this element 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 element is less than or equal to the number of payments per year, then the value of the <TermStep> element 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.

Attributes: 🔹AdjFirstInc

🔹 AdjFirstInc

If the value of this attribute is false, then the first rate increase following the teaser term is equal to annual rate increase. If true, then the first rate increase following the teaser term is equal to periodic rate increase defined above.

🟦 <TILARESPA2015>

The presence or absence of this element determines whether or not the TILA RESPA data table is present in the output.

If this element is present in the loan request, then the SCEX will return 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 this element is not present, then the TILA RESPA outputs will not be generated.

Attributes: 🔹MaxPnIDetails, 🔹MinPnIDetails

🔹 MaxPnIDetails

If the ARM loan specified a maximum lifetime interest rate (see <MaxRate>), 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 attribute to true.

🔹 MinPnIDetails

If the ARM loan specified a minimum lifetime interest rate (see <MinRate>), 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 attribute to true.

🟦 <TotalDown>

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

To generate a total down payment, please see the chapter detailing the SCEX’s Auto Prompts module.

Attributes: None