Skipped and Pickup Payment Loans - 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.

🟥 <inSKIPS_PICKUPS>

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, 🔹Country, 🔹DataDirPath, 🔹ForceReload, 🔹HideAmort, 🔹Lastday, 🔹MAPR_Max, 🔹Metavante, 🔹OddFinal, 🔹PmtDollarRound, 🔹PmtRound, 🔹PPY, 🔹UseIntOnlyNotSkips, 🔹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.

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

🔹 UseIntOnlyNotSkips

If this attribute is set to true, then any specified skipped payments (see the <IrregPmt> element) will be treated as interest only payments instead of skipped payments.

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

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

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

🟦 <InterestPmtRate>

If this loan has interest only payments preceding the irregular 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.

If no interest only payments precede the irregular loan, then this element may be omitted.

Attributes: None

🟦 <InterestPmts>

If present, this element determines the number of interest only payments which precede the start of the irregular loan. After the specified number of interest only payments are made, then the irregular loan continues for the number of payments specified in the <Term> element.

Also note that these interest only payments which precede the irregular payment loan are not affected by elements.

If this element is not present in the request, then no interest only payments will precede the irregular loan calculation.

Attributes: None

🟥 <IntRate>

The element data will determine the annual interest rate used for the loan. (Split rate loans require use of the setup files.)

The interest rate should be expressed as an annual percentage. For example, a loan computed with an interest rate of 6.125% would be specified as:

<IntRate>6.125</IntRate>

Attributes: None

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

🟦 <IrregPmt>[]

These elements allow the calling application to specify when skipped and/or pickup payments are to be included in the loan's repayment schedule. The element itself is empty, as all skipped payment data is contained it the element's attributes.

Attributes: 🔹Index, 🔹 Month, 🔹Payment, 🔹Year

🔹 Index

Instead of specifying a Month (and optionally, a Year) for a given skipped / irregular payment, you may optionally specify a payment number using the Index attribute. Thus, if you wish to specify that the first payment be skipped or irregular, you would set Index="1".

Interest only payments preceding the irregular loan (as specified by the <InterestPmts> element are not counted when specifying an Index.

Note that if you specify a payment index, then you should not specify the Month or Year attributes. If you do, the Index value will take precedence and the other two values will be ignored.

🔹 Month

The Month attribute allows the user to specify a month during which the skipped / irregular payment is applicable. If the Year attribute is not set for this element, then the skipped / irregular payment will be applied for each payment falling in the given month, throughout the entire term of the loan (excepting any interest only payments which precede the irregular loan).

On the other hand, if the Year attribute is set for this element, then the skipped / irregular payment will only be applied to those payments falling in the given month and year.

If the value of the Month attribute is set to zero (0), then this irregular payment specification applies to all payments in the loan. Since the loan must have at least one payment to compute, after specifying a month of zero, you will also need to specify an irregular payment entry with a payment amount of -1 (see the Payment attribute below).

If you wish to specify a skipped / irregular payment for a specific payment number (instead of specifying the month and optionally, the year), then use the Index attribute and do not specify a Month or Year attribute.

🔹 Payment

This attribute determines the type of irregular payment for the specified month (and possible year). A value of 0 (zero) indicates that the specified payment(s) should be skipped (or interest only, if the [UseIntOnlyNotSkips](#root.useintonlynotskips) attribute is true).

Any value greater than zero indicates that the specified payment(s) should be treated as pickup payments, with the value provided taken as the additional amount to be added to the computed regular payment.

A value of -1 (negative one), indicates that this irregular payment should be the computed payment.

🔹 Year

As discussed above, the Year attribute works closely with the Month attribute, and is entirely optional.

🟥 <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

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

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

🟥 <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

🟦 <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: None

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