APR Verification - 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.

🟥 <inREGZ_APR>

This is the root element of the XML APR message, and is required. This contains child elements which specify the particulars of the requested APR, as well as calculation results. The following attributes of the <inREGZ_APR> element are defined:

Attributes: 🔹DecAccuracy, 🔹HideAmort, 🔹Method

🔹 DecAccuracy

The number of decimal places of accuracy for the disclosed APR is determined by this attribute. The default value of this attribute depends upon the selected Method. For Actuarial and USRule, the default value is 3. For EU_APR, the default value is 1.

🔹 HideAmort

This attribute determines whether or not an amortization schedule will be included in the XML results, 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 XML output.

🔹 Method

In the United States of America, Regulation Z allows for APRs to be computed using two different methods: the actuarial method (Actuarial) or the US Rule method (USRule). In the European Union, there is a different method used (EU_APR) to compute the APR. The SCEX also supports the calculation of the internal rate of return as defined by Microsoft Excel’s XIRR() function (XIRR), as well as the internal rate of return based upon a unit period 360 days calendar (XIRR360). The IRR method implements a common spreadsheet internal rate of return method which assumes strict regular periods. Deviating from a strict regular periodicity may produce unreliable results. The YieldIRR method is similar to the IRR method, except the rate is converted to an annual yield equivalent, according to the payment frequency.

Use this attribute to specify the method used to compute the APR. If a value of USRule is specified, make sure to set the <USRule> element's attributes, as appropriate.

🟦 <ActuarialTweaks>

This element is only considered if the APR Method specified is Actuarial. The element itself contains no data. Instead, all of the information used to compute the fee is contained in the following attributes of the element:

Attributes: 🔹ForceSemimonth, 🔹OddDaysPrepaid 🔹SemiMonthlyFixedFraction, 🔹SinglePayFraction

🔹 ForceSemimonth

The computation of the unit period may mean that a loan may not be recognized as Semimonthly. This attribute overrides the default calculation in favor of a forced unit period as semimonth. This attribute should be replaced with its <UnitPeriod StandardPeriod="Semimonth" /> equivalent.

🔹 OddDaysPrepaid

Loans that have used an Odd Days Prepaid charge, common with mortgage loans, may use this attribute to adjust the APR to assume one unit period to the first payment. Otherwise, choose false.

🔹 SemiMonthlyFixedFraction

This setting is an unintended consequence of Appendix J to Regulation Z’s characterization of the fraction of a unit period for semimonthly loans. Applying the rules of Appendix J strictly to each payment in the payment stream results in an oscillating fraction of a unit period. For a constant fraction of a unit period, choose true. To apply the Federal Calendar to each payment, choose false. The latter should typically be selected with an irregular loan.

🔹 SinglePayFraction

This attribute only applies to single advance, single payment transactions of term less than one year. For these loans, when the term of the loan is a number of months, Appendix J allows for the term of the loan to be expressed as either a number of months over twelve, or the number of actual 24-hour days in the loan over 365. For the former, use "InMonths". For the latter, use "InDays".

🟥 <Advance>[]

This element represents an advance made during the loan. This advance amount is equal to the total amount earning interest less prepaid fees. One may think of these entries as streams of Amounts Financed (in the RegulationZ sense).

Attributes: 🔸AmtFin, 🔸Date, 🔹Freq, 🔹LastDay, 🔹Term

🔸 AmtFin

This attribute defines the advance amount for each of the Term advances. This dollar amount should be expressed as a number. For example, a request including Amt="10000.00" indicates a periodic advance of $10,000.

🔸 Date

This attribute contains the date on which this advance is started. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, an advance stream started on November 21, 2006 would be specified as Date="2006-11-21".

🔹 Freq

On the rare occasion that multiple, regular advances are streamed together, one may define the periodicity of these regularly occurring advances. Monthly advances are assumed.

🔹 LastDay

Were advances in this stream assumed to be the last day of the month?

🔹 Term

The Term attribute determines the number of advance events which occur with the given Freq. Most loans have a single advance, or advances at irregular periods, which is why one advance per stream is assumed.

🟦 <AmLine>[]

SCEX Amortization Schedules may be fed into the RegZAPR application in lieu of payment schedules. This option will be useful when one wishes to verify or get some insight into a particular disclosed SCE APR. One would copy and paste the entire amortization schedule as an expression of the payment stream.

For any other data entry, please use the <Advance>, <PmtStream> and <Premium> elements.

Attributes: see <AmTable>

🟦 <AmTableTweaks>

The amortization of a loan has many potential adjustments that can have an effect downstream within its amortization. Is interest rounded down? Or to the nearest penny? These slight variations or "tweaks" are identified and modified in this element.

The element itself contains no data. Instead, all of the information used to compute the fee is contained in the following attributes of the element:

Attributes: 🔹DollarDec, 🔹ForceDay, 🔹RoundInt, 🔹StrictTime

🔹 DollarDec

Dollar amounts within lines of the amortization schedule are disclosed as full floating numbers, which can produce long lines of amortization in the disclosure. The number of decimals for dollar quantities may be trimmed to the number of decimal places indicated by this attribute. Note that this number does not affect the calculation. It merely affects to what number of decimals places to which the floating point number is disclosed. ‘9’ means ‘do not trim’.

🔹 ForceDay

End of month considerations may require that a payment’s day was intended to be another day. For instance, if payments were intended to be made on the end of the month, and the first payment is in April, making this setting “31” causes the fed calendar to compute time as if the day of the payment were “31”, rather than 30.

🔹 RoundInt

If interest is rounded within the amortization schedule for US Rule loans, set the rounding method here.

🔹 StrictTime

Loans that have used an Odd Days Prepaid charge, common with mortgage loans, may use this attribute to adjust the APR to assume one unit period to the first payment. Otherwise, choose false.

When monthly payments are intended for the 29th or 30th of the month, how should the number of unit periods and fraction be calculated in February, when the day of the payment cannot be the intended day? (e.g. A non-leap year February where payments are meant for the 29th, but end up on the 28th). StrictTime acknowledges and disambiguates the calculation. Regular payments generally hold the fraction of a unit period constant, based on the date of the first payment. The SCEX allows for a constant fraction of a unit period or a strict time accounting, acknowledging that in February, the fraction of a unit period changes.

When the value of this attribute it true, the SCEX will calculate the fraction of a unit period strictly according to the rules of Appendix J of Regulation Z. A value of textfalse instructs the SCEX to keep the fraction of a unit period constant, equal to the fraction obtained by the time calculated from the date of the first payment to the transaction date.

🟦 <Construction>

Loans which have a construction period require data to be passed using this element. The element itself contains no data. Instead, all of the information used to define the construction period is contained in the following attributes of the element:

Attributes: 🔹AsPrepaid, 🔸EndDate, 🔸Interest, 🔹PermanentAttached, 🔹Prepaid

🔹 AsPrepaid

This attribute is only applicable when the attribute PermanentAttached is true. If the permanent loan treats the construction interest as a prepaid finance fee, then set the value of this attribute to true. On the other hand, if the construction interest is not treated as a prepaid finance fee and is instead included as a stream of interest only payments during the construction period, then set the value of this attribute to false.

🔸 EndDate

The date on which the construction period terminates.

🔸 Interest

The total amount of construction interest.

🔹 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. The default value of false indicates that this is solely a construction loan with no permanent attached.

🔹 Prepaid

This attribute holds the total prepaid charge for points and fees, excluding construction interest. This attribute need only be specified when the attribute PermanentAttached is false.

🟥 <PmtStream>[]

One or more <PmtStream> elements are required to specify the loan’s payment stream. For an equal payment loan, a single payment stream element is all that is required. For a balloon payment stream, you will need two. For highly irregular loans (skips, pickups, interest only, etc.) you will need many. The element itself is empty, as all necessary data for each payment stream is contained in the element’s attributes, which are described below.

Attributes: 🔸Begin, 🔸Pmt, 🔸Term, 🔹LastDay, 🔹PPY, 🔹SemimonthlyDay

🔸 Begin

This attribute contains the date on which this payment stream begins. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, a payment stream starting date of December 10, 2006 would be specified as Begin="2006-12-10".

🔹 LastDay

Were payments in this stream assumed to be the last day of the month?

🔸 Pmt

This attribute defines the principal and interest portion of the payment for each of the Term payments. If the total payment includes any protection products such as MOB life or debt protection fees, then these amounts must be removed as they are not a part of the principal and interest portion of the payment. This dollar amount should be expressed as a number. For example, a request including Pmt="500.00" indicates a periodic payment of $500.

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

The LoanBuilder module allows for semimonthly loans to be scheduled for two days that are not regularly 15 days apart, such as payments due the 1st and 17th of each month. These more exotic semimonthly loans can be computed using the SemimonthlyDay attribute of the <PmtStream>[] element.

🔹 SemimonthlyDay

When specifying a semimonthly payment stream, the day number on which the first payment is made determines the day number for all of the following odd numbered payments. If you omit this attribute or specify a value of 0, then the even numbered payments will be generated using the default method within the SCEX. If you wish to specify the day number on which even numbered payments fall (overriding the default method used in the SCEX), then set the value of this attribute to the desired day number. Setting the value of this attribute to ‘31’ will cause all even payments to fall on the last day of the month.

As an example, if you want to specify a semi-monthly payment stream beginning on January 1, 2020 with payments that fall on the Ist and 15th of each month for 24 payments, the element should look something like this:

<PmtStream 
   PmtType="CalcPmt" Begin="2020-01-01" Amount="###.###" 
   Term="24" PPY="24" SemimonthlyDay="15"
/>

🔸 Term

The Term attribute determines the number of payment events which occur with the given Frequency.

🟦 <Premium>[]

Only loans that have premiums occurring on dates not equal to the payment dates should use this element for expressing the premium. In the case of TruStage, for example, premiums are paid monthly on the same day of the month, regardless of when payments are made. In this case, please use these elements for entering loan premiums.

Attributes: 🔸Date, 🔸Prem, 🔹Freq, 🔹LastDay, 🔹Term

🔸 Date

This attribute contains the date on which this premium stream begins. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, a payment stream starting date of December 10, 2006 would be specified as Date="2006-12-10".

🔸 Prem

The amount of the voluntary loan protection. Do not include protection fees that are Mandatory, since they are APR affecting fees. The purpose of including these off-payment fees is to eliminate them from the APR.

🔹 Freq

The frequency of premiums is entered in a standard payments per year format. e.g. 4="Quarterly", etc.

🔹 LastDay

Was the premium intended for the last day of the month?

🔹 Term

The number of protection fees in the stream.

🟦 <TestAPR>

The SCEX will compute an APR for the given loan, then compare the APR it has computed against this value. The difference between the computed and test APRs will be compared. The SCEX will inform the calling application whether or not the provided APR is within compliance. If you do not have a test APR to compare, omit this element. The test APR should be expressed as a percentage. For example, a loan computed with test APR of 6.395% would be specified as <TestAPR>6.395</TestAPR>.

Attributes: None

🟦 <TestFinChg>

If this element is present and contains a value greater than zero, then the SCEX will compute the Regulation Z Finance Charge for the given loan and compare it to the value specified in this element. The magnitude of the difference between the computed and test values will be returned in the XML results. If this element is not present, or if it is present but contains a value less than or equal to zero, then the Finance Charge will not be returned in the XML results.

Attributes: None

🟦 <TestTotPmt>

If this element is present and contains a value greater than zero, then the SCEX will compute the Regulation Z Total of Payments for the given loan and compare it to the value specified in this element. The magnitude of the difference between the computed and test values will be returned in the XML results. If this element is not present, or if it is present but contains a value less than or equal to zero, then the Total of Payments is still returned in the XML results however no Difference or TestValue attributes will be present.

Attributes: None

🟦 <Transaction_Date>

The Transaction Date is generally the date of the first <Advance>. If, for instance, the finance charge begins beyond the date of the first advance, use this element to define the date the finance charge begins. All dates must be in the form of YYYY-MM-DD, and be 10 characters long. Hence, a transaction date of October 27, 2006 would be specified as <Transaction_Date>2006-10-27</Transaction_Date>.

Attributes: None

🟦 <UnitPeriod>

If this element is not present in the XML request, then the SCEX will compute the unit period. Including this element instructs the SCEX to use the unit period specified by the calling application. Please note that this element is empty, with all required data specifying the unit period passed as attributes of this element.

Attributes: 🔸StandardPeriod, 🔹Multiple

🔸 StandardPeriod

This attribute defines the standard unit period. The unit period will be some integral multiple of this standard unit period, as specified by the Multiple attribute below.

🔹 Multiple

This attribute defines the integral number of standard unit periods in the defined unit period.

As an example, if you wanted to specify a biweekly unit period, then you would include the following in the XML request:

<UnitPeriod StandardPeriod="Week" Multiple="2" />

Similarly, if you wanted to specify a quarterly unit period, then you would include the following in the XML request:

<UnitPeriod StandardPeriod="Month" Multiple="3" />

🟦 <USRule>

This element is only considered if the APR Method specified is USRule. The element itself contains no data. Instead, all of the information used to compute the fee is contained in the following attributes of the element:

Attributes: 🔹Calendar, 🔹CalendarTweak, 🔹Divisor, 🔹PremBeforePmt

🔹 Calendar

Actual day, unit period, and Federal calendars are supported with US Rule interest.

🔹 CalendarTweak

• True360 mans that each month is assumed to have 30 days in all respects. Typically, a loan computes the actual number of days from the Advance to the first payment to compute the Term Factor to the first payment.

• True365 means that February 29th is not allowed, both in counting days and assessing the days per year divisor.

• Midnight366 only applies to Actual/366 calendars, and means that a day is the time from midnight of one day to midnight of the other. The number of days between December 19th 2007 and January 19th 2008 would be 13 Days in a 365 year plus 18 days in a 366 day year, resulting in a Term Factor of “13/365+18/366”. An Actual/366 calculation not using the Midnight366 setting would compute the term factor as “12/365+19/366”.

🔹 Divisor

Choose the divisor, or number by which to divide the day count to produce term factors.

• 360 means take the computed days to the first payment and divide them by 360 to compute the term factor.

• 365 means take the computed days to the first payment and divide them by 365.

• 366 is understood to mean “366” only in a leap year. Any days accruing interest in a non-leap year use a 365 divisor. This setting may only be used with “ActualDay” calendars. PerPeriod means “360” for monthly and bimonthly periods, “364” for weekly multiples, Quarterly, and SemiAnnual repayments, and “365” for annual loans. VarDPY is understood to mean that the computed days to the first payment are divided by the number of days in the month of the transaction date, multiplied by twelve. 365.25 means take the computed days to the first payment and divide them by 365.25 to compute the term factor. This setting may only be used with “ActualDay” calendars.

🔹 PremBeforePmt

Are premiums processed before or after payments? “true” means premiums are amortized before payments, false means payments are processed before premiums.